Writing on software, systems, and hard-won lessons.
Writing on developer experience, systems thinking, and the mistakes behind both - covering AI workflows, continuous improvement, and the mental models that drive better decisions.
Writing on software, systems, and hard-won lessons.
Writing on developer experience, systems thinking, and the mistakes behind both - covering AI workflows, continuous improvement, and the mental models that drive better decisions.
AI coding agents are fast, but they don't know what you know. Without upfront planning, an agent will confidently scaffold an entire architecture around the wrong assumptions. And you won't notice until you're 50 files deep and untangling a mess that takes longer to fix than it would have taken to write.
I've been using AI coding agents everyday since mid 2025. The single biggest improvement to my workflow wasn't a better prompt or a new model. It was improving my planning process and restructuring my CLAUDE.md / AGENTS.md / GEMINI.md into a hot/cold path system.
This includes the footguns.md concept, which has been especially useful. Proactive rather than reactive documentation of cross-domain bugs, with a rule that the AI must log them before closing a task. That's a self-improving system.
This is the 4-step framework I run before any coding agent touches my codebase: Feature Brief, Technical Requirements, Milestones, and Context Files. Everything is copy-paste ready, the prompts aren't abstract advice. They're actual prompts you can paste into a terminal right now. That's what separates this from most "how I use AI" posts I've seen, and what drove me to share what works for me.
Feature Brief. Start with the initial requirements as you would without AI Assisted Development. This is the most important step and the one that most people skim over. The coding agent didn't attend that meeting last week, so it doesn't know what's most important until you let it know.
Technical Requirements. AI coding agents can scan the codebase to help expand the initial plan into something more detailed. This section includes a Mob Elaboration prompt to help you lock in the exact requirements by generating structured, targeted questions. It also introduces Signal-based adaptive orchestration (SBAO) to refine the plan by leveraging multiple agents to review and critique each other.
Project Plan with Milestones. Milestones make it easier to work on the right thing at the right time and help avoid context rot. Start with a proof of concept, then iterate toward something shippable.
Context files for AI Assisted Development. Good prompts help. Context files win. This section covers how to build a lean hot-path router and cold-path domain files so your AI always knows what it needs - and doesn't waste attention on what it doesn't.
Existing codebase with no context files? Go straight to the Context files section. Copy the prompts into your coding agent and ask it to build a hot/cold file strategy for your project.
New feature or project? Start with the Feature Brief. Create a requirements-<feature-name>.md, run it through the Mob Elaboration prompt, then use SBAO to pressure-test the plan with multiple agents before anyone writes code.
Ready to break work into tasks? Use the Milestone Planning prompt to structure objectives, exit criteria, and gotchas before handing off to a developer or agent.
Full templates and prompts at github.com/blundergoat/ai-planning-playbook.
A Problem Well Defined is a Problem Half Solved
Start with what problem or pain point you are trying to solve. Creating good quality requirements is a skill that takes practice. The more detailed and specific you can be, the better. Requirements should cover not just what the feature does, but who it's for, what systems it touches, what the constraints are, and how we will know if it's successful.
A brain dump is fine to start. It's most important that you understand why this feature request was made and how it benefits users. At the end of this process, you should have a clear and shared understanding that gives you the foundation for technical planning and building.
The full requirements-<feature-name>.md template - covering Problem & Outcome, Users & Use Cases, Scope & Constraints, System & Impact, Risks & Assumptions, Success Criteria, and Delivery Plan - is available here 01-feature-brief-template.md.
Now we have a clear feature brief, it's time to sharpen the plan. AI coding agents can scan the codebase and find gaps that might not surface until later. They can also ask clarifying questions early, before a developer picks it up. Two strategies help here.
The AI does not guess what you want - it generates structured, targeted questions. The team answers those questions to lock in the exact requirements.
# ROLE
You are an expert Technical Architect and AI Developer participating in a Mob Elaboration session. Your primary objective is to validate requirements and expose hidden complexities before any construction begins.
Do not write any code. Do not guess, assume business logic, or hallucinate features outside the stated scope.
# TASK
I will provide a high-level intent or feature request. Your job is to interrogate this intent. You must generate a structured, highly targeted list of questions to lock in the exact requirements.
# ELABORATION PROTOCOL
Analyze my intent and ask exactly 3 to 5 clarifying questions, focusing on:
1. **Business Logic & Constraints:** What are the hard rules, data limitations, or specific performance requirements?
2. **Edge Cases & Failure Modes:** What happens when inputs are malformed, external services fail, or system limits are reached?
3. **Architecture & State:** How does this specific feature integrate with the existing system design?
# INTERACTION & ARTIFACT RULES
1. **Halt and Wait:** After asking your questions, stop. Wait for my answers. We will iterate until I confirm the requirements are locked in.
2. **Synthesis:** Once I give the final approval, you will synthesize our discussion into structured artifacts.
3. **Context Separation:** You must separate the resulting plan into our established hot and cold files. Update the active, hot file (CLAUDE.md / AGENTS.md / GEMINI.md) with the immediate task breakdown, current state, and core execution rules. Any broader structural blueprints, such as generated Mermaid diagrams or system architecture maps, must be saved as separate, cold reference files.
Ask multiple coding agents for competing plans. Have them rank and rate each other's plans out of 100 and why.
SBAO the plan after writing the requirements yourself using multiple AI agents (e.g., separate chat sessions, Cursor multi-agent mode, different providers) and ask each one:
Deeply review the codebase and the following requirements (attach `requirements-<feature-name>.md`), and give me a technical plan in this file `TODO_feature-name_{model}.md`
Once the files have been created, ask the agents:
Rank each plan in a comparison table and rate them out of 100 and why
Review their ideas and pick the best ones. Then ask your preferred agent to synthesize:
I've reviewed these competing plans. Here's what I like and don't like:
**Keep:** [list the ideas, approaches, or architectural choices you want to keep]
**Drop:** [list what you disagree with or want to change]
**Decide:** [list open questions or trade-offs you want the agent to weigh in on]
Create a best-of-all-ideas plan in `TODO_feature-name_prime.md` that incorporates the Keep items, avoids the Drop items, and makes a reasoned recommendation for each Decide item.
LLMs Get Lost In Multi-Turn Conversation is a research paper about models anchoring on early guesses in long conversations. That's where milestones help us avoid context rot with shorter sessions or explicit "re-read the requirements" checkpoints.
So far we've started with a small plan, then sharpened and improved it. Now we need to structure that plan into actionable tasks. Each project is different, but the key is to start with a proof of concept that confirms the previous assumptions are correct and gives you something tangible to discuss.
I've heard people say "do it right the first time", but we know more at 25% than we did on day one, and that usually changes the plan.
The full milestone planning template with rules for spikes, assumption tracking, exit criteria, gotchas tables, and format guidelines, is here: 04-milestone-planning-prompt.md.
AI makes Big Design Up Front dangerously easy. We can generate a fully future-proofed architecture in seconds, but the deeper we get, the more the context rots and the harder it is to change.
By using the milestones above, we force the AI (and ourselves) into an Evolutionary model:
| Feature | The AI BDUF Trap | Evolutionary / Iterative |
|---|---|---|
| Primary Goal | Perfect initial execution | Continuous learning and adaptation |
| Risk Profile | High (back-loaded at launch) | Low (front-loaded in prototypes) |
| Cost of Change | Exponentially expensive | Stays relatively flat |
| Documentation | Heavy detailed, speculative | Living docs (like CLAUDE.md) |
| "Future Proofing" | Attempted via over-engineering | Achieved via simplicity and decoupling |
Persistent context files beat good prompts every time, but only if you separate your hot and cold paths. The size of your context files is a balancing act between the AI hallucinating (too small) and the AI suffocating (too big).
Your CLAUDE.md (or AGENTS.md / GEMINI.md) should act as a lean router. Keep the hot path small to preserve the AI's attention budget for the actual task, while the cold path ensures it never lacks the deep knowledge required to execute properly.
Create docs/code-map.md: a quick-reference tree map of the repository layout. Use this format:
project-name/
├── file.yaml = brief description
├── dir/
│ ├── subdir/ = brief description
│ └── file.go = brief description
└── other/ = brief description
Rules:
- Explore the full directory structure before writing
- One-line "= description" for every entry
- Call out generated/never-edit files explicitly
- Group related items but don't go deeper than 3-4 levels (summarize beyond that)
- Include key files by name when they're important (e.g. router.go, api.ts)
- Note ports, stack choices, and tools inline where relevant
- Keep it scannable: someone should understand the project layout in 30 seconds
Claude once re-enabled nonce validation on this Go + Next.js blog without checking whether the frontend could actually send one. Production login broke. LLMs are great at reading code but get lost navigating 40 files, trying to figure out how it all connects.
Get the agent to map it first.
Create docs/architecture.md with mermaid diagrams showing how this system works.
Include the following diagrams where applicable — skip any that don't apply to this project:
1. System overview: all major components and how they connect
2. Request flow: how a user request travels through the system
3. Authentication flow: how auth works end-to-end
4. Deployment flow: how code gets from dev to production
5. Data flow: how data moves between services/stores
Between each diagram, add 2-3 sentences explaining WHY things are wired that way, not just what the boxes are. Call out external services, cloud resources, and key infrastructure decisions.
The primary audience is an AI coding agent that needs to understand the system architecture before making changes. Optimize for scannability. Keep it under 150 lines.
Load the rules every time, load the details only when needed.
Create domain-specific instruction files in .github/instructions/ for each major area of this codebase. Each file should:
- Start with YAML frontmatter containing `applyTo` glob pattern matching the files it covers
(e.g., applyTo: "apps/api/**/*.go")
- Cover: project structure for that domain, conventions, patterns to follow, common gotchas,
"never do this" warnings, and a complete code example
- Be self-contained: an AI agent reading only this file should be able to work correctly
in that area of the codebase
- Include a "See Also" line pointing back to CLAUDE.md / AGENTS.md / GEMINI.md
- Target 200-400 lines per file
Create one file per distinct domain (e.g., backend language, frontend framework, database/SQL, tests, infrastructure/DevOps, HTTP handlers if they have unique patterns). Name them: {domain}.instructions.md
Explore the codebase first to discover the actual conventions and patterns in use: don't invent new ones. Extract rules from what the code already does.
Every line costs attention on every task. Make each one worth it.
Create a lean context file (~75 lines) that acts as a hot-path router.
Use the appropriate filename for your AI tool: CLAUDE.md / AGENTS.md / GEMINI.md.
This file is loaded into every AI conversation, so every line must earn its place. Structure it as:
1. Project identity (3-5 lines): stack, ports, one-sentence description
2. Essential commands (4-6 lines): only the commands needed every session (start dev, run checks, connect to DB)
3. Hard rules (8-12 lines): things that cause real breakage if violated. Only include rules where getting it wrong breaks the build, corrupts data, or causes production issues
4. Common workflows (8-12 lines): the 2-3 most frequent multi-step tasks as compressed numbered steps
5. Commit message format (3-5 lines)
6. Router table (~25 lines): three-column table mapping file paths to "read when..." triggers, grouped into domain guides, architecture & reference, and operations
Rules for the router table:
- Use task-language in "read when..." ("Writing Go code", not "Go conventions")
- Every referenced file must actually exist
- Group by: domain guides, architecture, operations
Do NOT include in the context file:
- Directory structure (belongs in docs/code-map.md)
- Detailed command lists (belongs in domain .instructions files)
- Full pattern explanations (belongs in .instructions files)
- Authentication details (belongs in dedicated auth docs)
- Troubleshooting tables (belongs in runbooks or .instructions files)
Explore the codebase and existing docs first. Cross-reference with .github/instructions/ and
docs/ to avoid duplication.
Troubleshooting is reactive ("something broke, now what?"), but footguns are preventive ("here's what will bite you before it does"). An AI reading footguns before making changes is higher leverage than an AI consulting troubleshooting after breaking something.
Read docs/footguns.md. If it doesn't exist, create it. Seed it with 2-3 footguns from this codebase - real cross-cutting issues you can find evidence of in the code, comments, or docs (not invented ones). Use this format per entry:
## Footgun: [short name]
**Symptoms:** What the developer or AI sees when this bites
**Why it happens:** Root cause spanning multiple domains
**Prevention:** Concrete steps to avoid it
Then add this line to the Hard Rules section of CLAUDE.md / AGENTS.md / GEMINI.md:
- **Log footguns.** When you cause a bug that spans multiple domains (e.g., API + frontend, infra + auth), append it to `docs/footguns.md` using the existing format before closing the task.
Bonus Tips
For an existing project, ask three different models this:
deeply review this project and rate out of 100 and why
For code reviews, from the PR in GitHub Copilot chat:
deeply review all the code changes in this PR AND review the github issue AND let me know if there's any blockers:
<paste GitHub issue url>
If this has been useful, feel free to star the repo and let me know what you built.
Full templates and prompts: github.com/blundergoat/ai-planning-playbook
What is claude insights: The /insights command in Claude Code generates an HTML report analysing your usage patterns across all your Claude Code sessions. It's designed to help us understand how we in...
A friend of mine recently attended an open forum panel about how engineering orgs can better support their engineers. The themes that came up were not surprising:
With chatbots and coding agents we've all experienced those moments that make us stop trusting the first answer. From cheerleading to making stuff up to drifting off course. That's why sometimes we ne...