AI workflows for features and fixes

Part 01

Groundwork for both workflows

An agent starts every session knowing nothing about your application. The setup below is done once per repository and pays for itself on every task afterward.

Part 02

Engineering a new feature

A feature in an existing app is mostly a question of fit: where the new behavior belongs, which existing code it should reuse, and what it must not disturb. The workflow front-loads that understanding so the code is written once.

1. Write down the outcome.

   State what a user will be able to do, what counts as done, and what is out of scope. Include the constraints the agent cannot guess: performance limits, compatibility, who is affected. A paragraph is enough; a one-line request is not.

2. Have the agent explore before it proposes anything.

   Ask it to read the relevant code and report back: how similar features are built, which modules it would touch, what data and interfaces are involved. No changes yet. This is where it learns your patterns instead of inventing its own.

3. Ask for a written plan, and review it.

   The plan should name the files to change, the approach, the tests to add, and any open questions. Reviewing a plan takes minutes; reviewing the wrong implementation takes hours. Correct the plan until you would be comfortable handing it to a colleague.

4. Settle the decisions that are yours.

   Schema changes, public interfaces, new dependencies, and anything touching security or billing should be decided by a person at the plan stage, not discovered in the diff.

5. Build in small, verifiable slices.

   Have the agent implement one slice at a time, with tests, running the test suite after each. A slice that works end to end is better than several layers that have never run together.

6. Verify in the running application.

   The agent should start the app and exercise the feature the way a user would, including the unhappy paths: empty input, missing permissions, a slow or failing dependency. Ask it to show what it ran and what it observed.

7. Get an independent review.

   Run a second review pass in a fresh session that has only the diff and the requirements, not the conversation that produced them. It catches what the author, human or AI, has stopped seeing.

8. Read the diff yourself, then merge.

   Check that the change does what the plan said and nothing more. Unrequested refactors, new dependencies, and widened scope are the things to push back on.

9. Release behind a control and watch it.

   Ship through your normal pipeline, behind a feature flag where the risk warrants it, and confirm the behavior in production before calling it done.

Part 03

Fixing an issue

A fix is an investigation before it is a change. The risk is not that the agent cannot write the patch; it is that it patches the symptom it was shown, and the real cause stays in place.

1. Give the agent the evidence, not your diagnosis.

   Provide the report as it came in: the error text, logs, steps to reproduce, the affected version, and what was expected instead. If you have a theory, label it as a theory. An agent handed a conclusion tends to confirm it.

2. Reproduce the failure first.

   Have the agent make the problem happen on demand, ideally as a failing automated test. If it cannot be reproduced, the task is to find out why, not to guess at a fix.

3. Find the root cause and state it.

   Ask for a plain explanation of why the failure occurs, traced through the code, with the evidence for it. If the explanation does not account for everything in the report, the cause has not been found yet.

4. Check how far the cause reaches.

   The same mistake often exists in neighboring code. Have the agent look for other places with the same pattern, and for data already affected by the bug that may need correcting.

5. Make the smallest change that removes the cause.

   A fix should be narrow and easy to review. Cleanup and refactoring the agent notices along the way go on a list for later, not into this change.

6. Prove it with the reproduction.

   The test that failed in step two should now pass, and the rest of the suite should still pass. Then repeat the original steps in the running app to confirm the reported behavior is gone.

7. Keep the test.

   The reproduction becomes a regression test. It is the only thing that stops the same issue from returning quietly.

8. Review, release, and confirm.

   Review the diff against the stated root cause, ship it, and check the original signal in production: the error rate, the log line, or the person who reported it.

9. Record what was learned.

   Note the cause and the fix where the team will find it, and add anything the agent should know next time to the project instructions.

Part 04

How the two differ

Part 05

What stays with the engineer

In both workflows the agent does the reading, writing, and checking. The engineer keeps the decisions: what should be built, whether the plan or the diagnosis is right, and whether the result is good enough to ship.

Three habits make that review effective. Ask for evidence rather than assurance: the command that was run and its output, not a statement that tests pass. Keep each task to one branch and one purpose so the diff can be read in a sitting. And when a session has gone down the wrong path, start a fresh one with a better brief instead of arguing the agent back on course.