I’ve been using Claude Code for the past year to ship features and fix bugs. I’m happy with it, but sometimes it’s challenging.
There were many cases where I would ask my agents to do something, and they would get most of it right, but almost every time I ended up replying “Great, but not exactly like that”.
That was on my good days. After a long session, my reply was just “bro, come on”.
Agents are a great tool, but they can get energy-draining pretty quickly. They remove the creative aspect of coding and can feel like you are constantly arguing with them. Not very fun, right?
The good news is that there is a solution to that. There are ways to teach your agents your personal taste and preferences, so they write and review code the way you would.
That’s how I stopped babysitting them and cut down on the back-and-forth.
Table of contents
Context
Just like humans, agents need the appropriate context to be productive. Engineers can’t fix a bug in a codebase without any business or product context, and neither can agents.
The more context agents can access, the better.
The first source is the codebase itself, along with the git history. Together, they can show when a bug was introduced or how different components are connected.
Next is issue-tracking software like Jira or Linear. A ticket contains discussions between engineers and stakeholders and provides information such as the decisions that were made and the reasons behind them.
Error-monitoring tools are another source. For instance, stack traces provide very useful information to help fix a bug.
Most of these tools already have MCP (Model Context Protocol) servers or command-line tools that agents can use before they start working on a bug or a feature.
The tricky part is that “garbage in, garbage out” applies to context too.
For this reason, the context must be as clean and useful as possible.
The git history must be clean, tickets short and simple, and the error-monitoring tools well configured.
Tickets matter the most because they’re where the agent starts. A good ticket describes the problem to solve, never the solution. If the solution is included in the ticket, the agent will follow it without question.
Bad example:
## 🚀 Overview
This ticket aims to enhance the robustness and
reliability of our webhook delivery system by
implementing a comprehensive retry mechanism.
## ✅ Proposed Solution
1. Implement exponential backoff with jitter
2. Add a `retry_count` column to the `webhook_events` table
3. Create a dead-letter queue for failed deliveries
## 🎯 Acceptance Criteria
- [ ] Retry mechanism is implemented
- [ ] Code is well-tested
- [ ] Documentation is updated
The bad example does not contain data or user impact, and it hands the agent a solution before anyone has thought about the problem.
Good example:
Merchants miss payment confirmations when their webhook endpoint times out
## What is wrong
When a merchant's endpoint times out, we mark the
webhook as failed and never retry. Their orders stay
"unpaid" even though the payment went through.
This happened 37 times last week (see the dashboard link).
## Expected result
Merchants eventually receive every payment confirmation.
The good example describes the problem clearly, backs it up with data, and states an expected result. That result is the goal for the agent. It considers the ticket done only when the expected result is met.
Codebase
The codebase is how the agent learns what good code looks like.
Agents tend to copy patterns that already exist in the codebase, so ideally most of the codebase should have good code and architecture.
For example, if the codebase follows the Clean Architecture throughout, the agent will build the next feature using the same architecture.
However, if the codebase mixes good and bad patterns, the agent can’t tell which one is right. Take these two services:
services/
├── invoices/
│ ├── handlers.go # HTTP handlers that also run SQL queries
│ ├── models.go
│ ├── utils.go # 800 lines of unrelated helpers
│ └── helpers2.go
└── payments/
├── domain/
│ ├── payment.go # entities and business rules
│ └── repository.go # interfaces
├── usecase/
│ └── complete_payment.go # application logic
└── adapter/
├── http/
│ └── handler.go # turns HTTP requests into use case calls
└── postgres/
└── payment_repository.go # implements the repository interface
When I ask the agent to build a new service, there’s a high chance it will copy the
first one, especially if the new feature is close to invoices.
Since agents copy what they see, every bad pattern that gets in eventually gets multiplied.
This matters because shipping code is cheap now, so it’s very easy to pollute a codebase with bad patterns. Keeping it clean takes significant attention and requires reading the code.
Verification
Asking an agent to implement a feature is only 50% of the work. The other 50% is verification, so agents need a way to check their own work.
Unit and integration tests are not enough. Agents should also test end to end, and to do that, they need to know how to run the project.
The codebase must document how to run it and how to test it.
For example, this is how I document a Go API. I keep these instructions in AGENTS.md,
a file that agents read automatically at the start of every session:
# Payments API
## Run locally
1. Start the dependencies: `docker compose up -d postgres`
2. Apply the migrations: `make migrate`
3. Seed test data: `make seed` (creates a test merchant, `m_test`)
4. Start the API: `go run ./cmd/api` (listens on port 8080)
## Test
- Unit tests: `go test ./...`
- Integration tests (need the database): `go test -tags=integration ./...`
## Verify a change end to end
1. Start the API as described above.
2. Call the endpoint you changed, for example:
`curl -X POST localhost:8080/v1/payments -d '{"merchant_id": "m_test", "amount": 1000}'`
3. Check the response and the API logs: `make logs`.
4. If anything fails, fix it and start again from step 1.
With this, the agent can run the API, call the endpoint it changed, check the logs itself, make any necessary fixes, and repeat until the ticket’s expected result is met.
Skills
I use agent skills to automate the repetitive parts of my work, so I don’t have to babysit the agent. Skills are reusable instructions, written as Markdown files, that the agent loads when a task needs them.
Human-readable text
When agents write tickets, commit messages, and pull request descriptions, they tend to generate huge blocks of text that are unreadable for humans and just create noise. Hardly anyone reads an AI-generated ticket or pull request description.
For this reason, I have a skill for each one of them that describes what makes a good ticket, commit message, and pull request description.
For example, compare these two pull request descriptions:
Bad example:
## 📝 Summary
This PR introduces a comprehensive and robust retry mechanism for webhook
deliveries, significantly improving the reliability and resilience of our
payment notification system. 🎉
## 🔧 Key Changes
- **Service Layer:** Created a new `WebhookDeliveryService` struct to
encapsulate webhook delivery logic, improving separation of concerns
- **Data Model:** Added an `AttemptCount` field to the `WebhookEvent` struct
- **Handler:** Updated the webhook HTTP handler to leverage the new service
- **Database:** Added a migration for the new column
- **Tests:** Updated tests to reflect the changes
## 🧪 Testing
- ✅ All tests pass
- ✅ Manually verified that the changes work as expected
## 💡 Benefits
- Enhanced reliability
- Improved maintainability
- Better developer experience
## ⚠️ Breaking Changes
None
## 🚀 Future Improvements
- Consider adding a dead-letter queue
- Explore adding metrics and alerting
## 📈 Impact
This change will greatly enhance merchant satisfaction and ensure a
seamless payment experience.
Good example:
Retry failed payment webhooks so merchants stop missing payment confirmations
- Retry failed deliveries up to 5 times with exponential backoff
- Store the attempt count and last error on the webhook_events table
- Move delivery logic from the HTTP handler into the usecase layer
- Add tests for retry exhaustion and successful redelivery
The good example is short and clean enough for both humans and agents to read and review.
This is the skill that produces it:
---
name: pr-description
description: >
Write a pull request description.
Use when opening or updating a PR.
---
Format:
- First line: what the PR does, max 200 characters.
- Then 3–5 bullets with the key changes, max 200 characters each.
Rules:
- Say what changed and why. The diff already shows how.
- No headings, no "Summary"/"Testing"/"Impact" sections, no emoji.
- Don't list files, reviewers can see the diff.
I can run it directly with /pr-description, or the agent picks it up on its own
when I ask it to open a pull request.
This way, everything my agents read later, from tickets to git history, is clean context.
Clean code
I also use skills to teach the agent my personal taste in code. I have a skill called
/add-code-rule that adds a rule of my choice to a RULES.md file that is always
in my agent’s context, so it writes and reviews code the way I would.
When I add a rule, I also write a bad and a good example myself, because a concrete pair teaches the agent more than the rule on its own.
For example, running /add-code-rule "Variable names should be self-explanatory"
and giving it my examples adds this entry to RULES.md:
## Variable names should be self-explanatory
Bad:
func calc(a, b, c int) int {
return a + b - c
}
Good:
func calculateFinalScore(baseScore, bonusPoints, penalty int) int {
return baseScore + bonusPoints - penalty
}
Since I can’t list every rule I’ve picked up unconsciously over years of writing code by hand, I also created a hook. If you’ve used git hooks, it’s the same idea. A script that runs automatically at a certain point. In my agent, I configure it to run every time the agent finishes responding:
{
"hooks": {
"Stop": [
{
"hooks": [
{ "type": "command", "command": ".agent/hooks/suggest-rule.sh" }
]
}
]
}
}
The script checks whether the agent changed any code. If it did, the script sends the agent back along with the instruction to look at my last request and turn it into a candidate rule.
So when I tell the agent “don’t nest these ifs, return early”, it finishes the change and then asks:
Your last request sounds like a general rule:
"Return early instead of nesting if statements."
Should I add it to RULES.md?
I approve or reject each suggestion, so the file only contains rules I actually agree with.
This way, I minimize the back-and-forth since the agent writes code the way I would, without me having to ask it to change things.
Code review
Since agents arrived, the pull requests I have to review have grown enormously, both in number and in size. I handle that in two steps:
- A reviewer agent goes first
- I review the code myself
The reviewer agent
The reviewer agent is not a skill. It is a subagent with its own instructions
and a clean context, so it isn’t biased by the reasoning of the agent that wrote the
code. It checks the change against my RULES.md and a few other criteria I personally
find important. These are different for everyone.
A very simplified version of mine looks like this:
---
name: reviewer
description: >
Reviews a code change against my rules.
Use after an implementation is done.
tools: Read, Grep, Glob, Bash
---
You are reviewing a change you didn't write.
1. Run `git diff main` to see the change.
2. Read RULES.md and check every changed line against it.
3. Also check:
- Does the change solve the ticket's problem, and nothing more?
- Do new behaviors have tests, and do they test
behavior rather than implementation?
- Are errors handled, not silently swallowed?
- Is there dead code, debug output, or commented-out code?
4. Run the tests.
Return a list of findings: file, line, the rule or check it breaks,
and a suggested fix. Don't change any code yourself.
My own review
Manual review is still important, so my last skill helps me with that. It gives me the list of changed files in an order that makes them easier to review:
- Files with new behavior, algorithm or state changes, or changes to the API surface
- Tests for those changes
- Wiring and integration, such as routes, URL configuration, and dependency injection
- Boilerplate
For the webhook pull request above, it looks like this:
Behavior
- services/payments/usecase/deliver_webhook.go
- services/payments/domain/webhook_event.go
Tests
- services/payments/usecase/deliver_webhook_test.go
Wiring
- services/payments/adapter/http/handler.go
- services/payments/adapter/postgres/webhook_event_repository.go
Boilerplate
- migrations/0042_add_attempt_count.sql
This way, I start with the files that need the most attention and finish with the ones I can skim.
My workflow
I follow a specific process when building features. I start with a spec, usually a Jira or Linear ticket. It describes the problem that needs to be solved.
I ask the agent to read the ticket and gather the relevant context by digging into the codebase.
After that, I ask it to ask me questions rather than propose a solution. In this Q&A, we discuss the approach, the trade-offs and the solution. The final decision is mine, not the agent’s. Afterwards, I ask it to build it.
For the webhook ticket above, the Q&A went roughly like this:
Agent:
I read the ticket and the webhook code. A few questions before I build anything:
1. Retries mean merchants may receive the same webhook twice, and the payload
has no event ID, so they can't detect duplicates. Should I add one?
2. Should retries run inside the request or in a background worker?
There's already a worker in cmd/worker that sends emails.
3. How many attempts, and over what period? Merchant endpoints can be
down for hours.
Me:
1. Not in this PR. I'll create a separate ticket for it.
2. Background worker.
3. Five attempts with exponential backoff, spread over about a day.
Agent:
Then I'll store the attempt count and last error on webhook_events, and move
delivery into the usecase layer so the HTTP handler and the worker can share it.
Does that work?
Me:
Yes, but keep the handler change minimal.
The ticket never mentioned retries or backoff. That decision came out of this conversation.
When it’s done, I hand the code to my reviewer agent. The reviewer sends its findings back to the first agent, which addresses them.
Then I run the review a second time. This is purely empirical. I’m not sure why it works, but two rounds of review produce better code than one.
Finally, I review the code myself, make any necessary changes, and open a pull request.
Conclusion
I still experiment with and improve my setup every day. I keep reading about the industry and trying new tools. I hope this was helpful, and I’d love to hear what works for you :)