How I code with agents
I’ve been coding with AI agents for over a year now. And I wanted to share a few tips.
- First rule you should force agents to follow, is the same rule you start with when working on a big codebase: Understand the scope of change, before planning the implementation. If you’re gonna touch something, make sure to read what everyone does with it.
- (Biggest one) Maintain a high-quality project context by forcing the agent to maintain a /docs folder next to your code. It’s the live contract. And these are the things you need docs for in rough order of importance:
- What it is (a brief of the business)
- System overview
- Data flow
- Architecture
- Features
- Runtime flows
- DB schema
- Practices
- An index of all above referenced in CLAUDE/AGENTS.md. The agent only pulls the related ones helping you with context budgeting. Which is my next point:
3. Don’t go over 40% of your agent’s context limit. If your change is big, break it into smaller phases and spin up new agents for each phase.
Get Masoud Bonabi’s stories in your inbox
Join Medium for free to get updates from this writer.
4. This might seem obvious, but let’s put it in here anyways. Don’t delegate the thinking! Get help weighing pros and cons of decisions, but don’t delegate it upfront. See what you’ll lose for what you gain.
5. Before asking your main question, ask a smaller one forcing it to build the right mental model first.
6. Agents get biased too. Separate gap-finding of your initial plan from planning. And definitely separate code review, from execution.
7. A surprising workflow is: analysis → planning → gap-finding → phasing → execution → code review. Most agent failures come from skipping one of these steps.
8. /grill-me for help planning big changes. It basically “Interviews you relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree” helping you scope changes specifically. It can also help keeping the agent grounded to your desired scope, preventing it going above and beyond. (By Matt Pocock)
So let’s split the work: you keep the thinking and the architecture, the agent keeps the context and the typing.
What did I miss, and which step do you think people skip the most?
