Skip to main content

AI Feature Development Workflow

Give a coding agent a bounded contract, then verify the implementation before merge.

Introduction​

A coding agent can read a repository, build a feature, and run checks across several files. It works best when the expected behavior and the boundaries are clear. You stay responsible for the design and for the diff you accept.

Use this workflow for well-defined changes you can accept or reject on observable behavior.

Understanding the Workflow​

A task contract sets out the user-visible behavior, the scope, the constraints, and how you will check the result. It tells the agent enough to start digging without spelling out every step.

Definition

Task Contract

A bounded description of required behavior, scope, constraints, and acceptance checks for an implementation task.

The agent works in an isolated workspace with its own files and branch, usually a Git worktree. That keeps your other work safe from its edits and commands. It does not make the output safe to merge.

Definition

Isolated Workspace

A separate worktree, workspace, clone, or sandbox where one task can change files without overwriting another task's working copy.

Applying It in Practice​

Write the task contract before opening the agent session. Include:

  • required behavior and acceptance criteria
  • explicit exclusions
  • relevant files, modules, and existing patterns
  • compatibility and security constraints
  • tests and commands that must pass

For example:

Add an archive endpoint at /api/users/{id}/archive in src/api/users.rs.
Mark the user as archived and return the updated record.
Return 404 when the user does not exist.
Do not delete the user or change the existing response shape.
Add integration tests for success and missing-user cases.

When a task crosses module boundaries or has more than one sane design, ask the agent to read the code and lay out its plan first. Fix wrong assumptions before they spread through the diff.

Let the agent build and run its checks in the workspace. Step in when it drifts out of scope, rebuilds something that already exists, or works from a false assumption. Waiting for it to finish is expensive once the direction is wrong.

Review the complete diff in this order:

  1. required behavior and scope
  2. architecture and existing conventions
  3. errors, empty states, and security boundaries
  4. tests and their failure sensitivity
  5. dependencies, configuration, and generated files

Point every comment at observable behavior or at a specific line. Rerun the tests, the static checks, and the production build after each revision. Then use your normal human review and merge process.

Engineering Considerations​

Do not hand off a change nobody on the team can review. Passing tests and a confident summary do not make it correct.

Narrow tasks cut the context the agent has to find on its own. They also yield smaller diffs, which are cheaper to review and make a wrong assumption easier to spot.

Use test-driven development when the repository calls for it, or when you can pin down the behavior up front. Read the failing test before you accept any production change.

Exploratory product work needs a different process. Settle the user problem and the design first, or keep the agent on research and throwaway prototypes.

Scaling and Operations​

Review capacity is what caps parallel agent work. Starting ten tasks helps nobody when the finished diffs sit unread or get waved through.

Give each agent its own workspace and branch, as in running coding agents in parallel. Say who owns what when tasks touch shared interfaces. Run dependent tasks in order, or settle the interface before they start in parallel.

Limit credentials and commands to what the task needs. Keep the prompt, the tool output that mattered, the checks, and the final diff when a change carries operational or compliance weight.

Track rework by kind of task. When one class of work keeps failing, something has to change: the task contract, the repository guidance, the automated checks, or the decision to delegate at all.

Next Steps​