Build by Parts

How to build a complex feature by decomposing it into tasks.

In many cases, we can build a feature by giving a coding agent a tech spec. For complex requirements, this is not advisable, for two reasons.

1. We often don’t know what we want. Often, we start by building a walking skeleton¹ or a tracer bullet², learn, and make changes along the way.
2. The language model behind the coding agent has a limited context window. Keeping each session small is a best practice.

I have a workflow for building a complex feature which I call “Build by Parts”. This essay describes my workflow.

Vocabulary

• Feature - The top-level organizational unit of work. A feature corresponds to a tech spec.
• Task - A subunit of work under a Feature.
• Agent - Roles AI agents take on during the project build: Lead, Builder, and Evaluator agents. The group of agents that participate in building a project is called an agent team.
• Lead - The lead agent is responsible for creating agents and delegating work to them. Its responsibility is to track project progress, make decisions, and set the standard for quality. The lead provides answers to project status and keeps the engineer informed of changes to the tech spec and project plan.
• Builder - The builder agent is responsible for implementing specifications for a specific task. It needs to research and understand the codebase, write and test the code.
• Evaluator - The evaluator agent is responsible for assessing the work done by the builder agent. It tests the code, evaluates quality, and reports its assessments to the Lead. The Lead uses the assessment to decide what to do.
• Engineer - The human who is using the agent team to build a feature. The engineer determines the amount of autonomy given to the lead agent and provides project guidance.
• Build Project - The organized work which consists of Project Documents and is carried out by the agent team.
• Project Documents - A project plan, a test plan, the tech spec, project guidance, and a project history document. The documentation is used by the lead to stay informed of the project so that it can answer questions about the project.
• Tech spec - The detailed description of a feature. It describes the requirements and architecture decisions.
• Test plan - A document, distinct from the tech spec, that describes what to test. The tech spec specifies requirements. The test plan clarifies the feature through test conditions and forces the engineer to verbalize the most important properties to verify.
• Project Plan - Tasks, their description, status, and dependencies. The lead updates this document as tasks are completed and uses it to keep the engineer informed.
• Project Guidance - Notes from the engineer to the lead, specific to this build. Here are some ways an engineer might use guidance: Spend no more than $25; Give agents more or less autonomy depending on how sensitive the project is; Use this method to keep me informed.
• Project History Document - Copies of the original tech spec and test plan shall remain immutable artifacts throughout the build. Changes to the spec and test plan and key decisions made during the build shall be documented here. Written by and read by the lead agent – the engineer rarely reads this document.

The Workflow

Assumption: AI does much of the work. The engineer directs.

1. Break a feature into tasks.
2. Write project documentation.
3. Approve tech spec, test plan, project plan, and project guidance.
4. Tell the lead to start the build.
5. Make decisions as the lead raises them. Occasionally check in and provide unprompted guidance to steer the build. Provide sign-off on verifications where appropriate.
6. Final verification of the build.
7. Lessons learned from the build: How can the workflow improve? How can the process used to carry out the workflow improve? How should my mental model of an agent team and build project evolve?

Breaking Down a Feature

This essay does not try to prescribe how to break down a feature. I do advise starting with a walking skeleton or tracer bullet and using the learnings to refine the project plan.

What the Lead Does

The lead is given the project plan and it will start building the project from there.

1. It reviews project documentation and makes sure nothing major is amiss.
2. For each task:
   1. It creates a builder and hands it the task, tech spec, and test plan. The builder builds and tests the task and reports back to the lead when the task is finished.
   2. When the builder is finished, the lead creates an evaluator to assess the builder’s work.
   3. The evaluator evaluates the work and reports back.
   4. The lead then decides: accept the work, send it back to a builder, or raise a question with the engineer.
3. Along the way, the lead keeps the project plan and the project history document current, and raises decisions with the engineer as the project guidance calls for.

How the lead orders tasks, how many builders it runs at once, and what it does when a task goes badly are up to the lead.

Examples

Project Plan

For the most part, we can use a text file as a project plan. However, when working in a professional setting, we might be required to use project management software such as Jira to capture the project plan.

Here is one possible shape of a project plan:

# Make A Cookie

## Tasks

### COOK001 - Acquire money
<description>
  
### COOK002 - Buy ingredients
<description>

### COOK003 - Mix dry ingredients
### COOK004 - Melt butter 
Not clear when to start this. Play it by ear. We just need the melted butter by the time we combine wet ingredients. 

### COOK005 - Combine wet ingredients
Combine melted butter, sugars, eggs, and vanilla extract

### COOK006 - Combine wet and dry ingredients
### COOK007 - Bake
The cook should verify the state of baking at 40 minutes, then repeatedly verify. Do not re-verify every minute though...

## Related Documents

- Tech spec: ...
- Test plan: ...
- Project guidance: ...

## Change Log

<Tasks added, dropped, or changed, and when.>

Project Guidance

# Project Guidance
## Guidance
Use no more than $25 on ingredients. The AI has authority to fine-tune ingredient proportions. The AI can estimate when to start melting butter to avoid downtime. 

<More instructions...>

## Change Log

<Some sort of history of changes to the project guidance as the build progresses>

Project History Document

There is no example here because it is written by the lead agent, for AI agents. And much of its shape will vary depending on external conditions. The requirements:

• The lead agent writes it
• Keeps track of changes to the spec, changes to key decisions, changes to architecture, etc.
• Records whether each task is done, in progress, or not started

This project history document helps the lead agent answer questions about the project and it can minimize the impact of session compaction. If the project plan lives in something like Jira, much of this is already tracked there, and the document shrinks significantly.

Anti-Patterns

The test plan that covers everything. The value of a test plan is not that it proves to the reader that every test is covered – AI does not lack for fastidiousness. The value of a test plan is for you to express which behaviors are so important that it is worth your time to write it down.

Editing the original in place. Allowing the lead to change the tech spec or test plan directly instead of recording the change in the project history. Without a separate place to record changes, the lead asks you before every change. AI tends to be more autonomous when asked to track changes in a separate document.

Conclusion

This essay provides you with the tools you need to define your own workflow. Once you have defined it, you should turn it into agent skills so you can apply it consistently.

• AI
• Programming