Skip to content

Build a Feature

In this tutorial, you'll use the Build agent to generate code that matches your codebase's patterns and review every change as a diff before it reaches the repository.

Prerequisites

  • Potpie CLI installed and set up (Quickstart)
  • A repository registered and parsed to ready status

Workflow

1. Load existing patterns

Before describing the feature, have Potpie surface the conventions Build should follow. This grounds the generated code in your actual codebase:

potpie resolve "conventions for adding middleware" --intent feature

Middleware pattern (app/middleware/):
- Each middleware is a class with an async __call__(self, request, call_next)
- Registered in app/main.py via app.add_middleware(...)
- Config read from app/config.py Settings (pydantic BaseSettings)
- Redis client provided by app/deps/redis.py:get_redis()

2. Describe the feature

Enter a description of the feature you want to build. Be specific about the desired outcome.

> "Add a rate limiting middleware that uses Redis and supports per-route configuration"

3. Answer clarifying questions

Potpie surfaces multiple-choice questions to lock in scope and requirements before the specification begins. Each option is derived from what Potpie actually finds in your repository.

1. Rate-limit key strategy?
   (a) Per IP   (b) Per authenticated user   (c) Per API key
2. Behavior when limit exceeded?
   (a) HTTP 429 with Retry-After   (b) Silent drop   (c) Queue
3. Where should per-route limits be configured?
   (a) Decorator on route   (b) Central config map   (c) Both

4. Review the specification

Potpie generates a specification covering:

  • Every file to create or modify
  • Implementation details for each change
  • Dependency relationships between affected components

5. Review the plan

The plan includes three views:

An explanation of what changes, which parts of the codebase are in scope, and how the new code fits the existing system.

A dependency graph showing how new components wire into existing services, data models, and API boundaries.

Each task lists the target file, implementation intent, dependency order, and verification criteria.

6. Review generated code

Code is generated and presented as diffs. Changes match the existing code style and conventions identified during specification.

7. Create a pull request

Once you're satisfied with the diffs, create a PR directly from the generated changes.

Tips

Tip

The more specific your initial description, the fewer clarifying questions Potpie needs to ask. Include constraints, boundaries, and expected behavior upfront.

Info

Build reads the knowledge graph for established patterns, naming conventions, dependency direction rules, and prior architectural decisions before generating any code.

Next steps