Skip to main content

1. Planning Phase (~ 30–90 minutes)

Guided Coding workflow diagram highlighting the Planning Phase. The three phases are Planning, Implementation, and Guiding, with arrows showing iteration back to Planning for large issues or back to Implementation for small issues.1. Planning Phase2. Implementation Phase3. Guiding Phase✓ PR

Let the agent plan with you​

Start a new conversation with your coding agent and iteratively create a plan together. This is essentially breaking down requirements into technical tasks with the agent's help:

  • Don't use your Coding Agent's "planning mode". I don't use the built-in "planning mode" of coding agents. There is no iteration involved, and plans typically do not end up in your git repo. The default Agent mode is enough, you steer the conversation actively.
  • Give the agent a role. I use something like "With you being an expert .NET architect" in my first prompt of the planning phase. This focuses the agent on planning rather than jumping into implementation. Assigning roles tends to produce better results in my experience.
  • Discuss the feature. Ask the agent how it would approach the problem. Review its suggestions about elements like design, refactorings, testing, and performance. Bring your own thoughts and questions to the table — this is a conversation, not delegation.
  • End with repeated sanity checks. At the end of the planning phase, I typically ask "Would you change anything about the plan?" This often catches things I didn't think of. Do this repeatedly until the plan stabilizes.
  • Commit the plan as a markdown file in the git repo. They serve as a project-specific immutable decision record. They form a history, similar to Event Sourcing.

Plan Structure​

After some experimentation, I settled on three sections which are quite common in Agile Development:

  1. Rationale — Why do we want to build this? Why is this feature needed or why does this bug need fixing? This gives the agent context for the greater goal.
  2. Acceptance Criteria — Bullet points that must be fulfilled for the feature to be approved. The agent in the implementation phase will use these to check off each aspect of the feature after it's been implemented.
  3. Technical Details — Important parts of the codebase, extension points, types to modify or add, and design direction.

Of course, you are free to use your own structure.

Keep plans focused. With Anthropic models in particular (Opus, Sonnet), plans tend to become very detailed with implementation phases and step-by-step instructions that the agent doesn't actually need. The models are smart enough to figure out the implementation order themselves. A plan that's too detailed can actually steer the agent in the wrong direction, because if you missed something, the overly prescriptive structure leaves no room for the agent to adapt. Therefore, use AGENTS.md or a skill to limit the plan size.

A plan is not an epic, a user story, or an initiative — it should contain technical details. You should have technical knowledge to discuss and review these plans effectively.

Steering Plan Structure with AGENTS.md​

To steer agents to write plans in the aforementioned structure, I usually place this file in ai-plans/AGENTS.md. Read the contents carefully. You might need to adjust them for your specific project. This AGENTS.md also contains instructions for writing plan deviation files, see the Guiding Phase for when this document is needed.

# AGENTS.md for AI plans

*Version 1.1*

This directory contains Markdown plans and plan deviation records, plus this instruction file. These documents follow the [Guided Coding](https://kenny-codes.net/docs/guided-coding/) approach.

File names begin with the four-digit GitHub issue number and a short kebab-case description. When an issue has multiple documents, insert a zero-based sequence after the issue number, for example `0015-0-feature.md`, `0015-1-optimization.md`, and `0015-2-plan-deviations.md`. Do not rename or restructure completed historical plans solely to conform to the current rules.

## How to Write Plans

1. Every plan starts with a `# Title` and contains exactly three sections, in this order: `## Rationale`, `## Acceptance Criteria`, and `## Technical Details`.
2. The Rationale briefly describes the problem and the overarching goal of addressing it. Keep it to one or two short paragraphs unless additional context is necessary to understand the change.
3. Acceptance Criteria contains observable and verifiable outcomes using Markdown task-list items (`- [ ]`). Describe what must be true when the work is complete, not the individual implementation steps.
4. Technical Details records the important implementation decisions, constraints, affected components, and non-obvious interactions. Include enough information for an implementer to understand the intended design without prescribing the complete implementation. Assume the implementer is a senior software engineer.
5. Use code examples in Technical Details when they define an important contract more clearly and concisely than prose, such as API signatures, central interfaces, or DTO shapes. Keep them minimal, omit implementation bodies and routine context, and identify them as exact or illustrative when this is not obvious. Avoid step-by-step instructions, exhaustive file lists, and background knowledge expected of a senior software engineer.
6. When behavior changes, include an acceptance criterion requiring appropriate automated test coverage. Describe specific test cases in Technical Details only when they are not obvious from the acceptance criteria.
7. Include microbenchmarks only for changes where performance is a relevant risk or requirement. Add them to Acceptance Criteria and describe benchmark scenarios in Technical Details only when those scenarios are not self-evident.
8. Keep plans concise. Prefer decisions, constraints, and outcomes to explanations of routine implementation work.

Use these rules for follow-up plans, too.

## How to Write Plan Deviation Files

When users find substantial issues in the Guiding Phase and create new plans to fix these, a single plan deviation file sums up the differences from the original plan and its follow-up plans. They do not use the same structure as plans, you can use any format that clearly communicates the differences. Often, a feature-based approach is appropriate.

While the format is flexible, include the following information:

- Reference every plan included in the comparison.
- Describe what was originally specified, what the codebase actually does, and why the change was made.