Bringing Claude Code into a dev team without creating debt

A coding agent saves time from day one. The debt arrives later: code that passes the tests but that nobody on the team can explain, conventions applied half the time, documentation describing a system that no longer exists. None of these debts is specific to AI. AI just produces them faster.

Here are the guardrails I use in my own repositories — the same ones I offer to set up in a team.

Write down what the agent needs to know

A developer joining the team learns the unwritten rules in a few weeks. An agent starts from zero every session. Everything that matters must therefore be written down, in the repository, versioned and reviewed like code: a CLAUDE.md at the root (stack, structure, conventions, dependency direction, known pitfalls), and procedures for recurring tasks — adding a page, fixing a bug, reviewing a PR.

This document is written with the team, not for it. It is the moment you discover that three people were applying three different conventions: better to settle it before the agent invents a fourth.

Make the rules executable

A rule written in a Markdown file is a wish. A rule checked by CI is a rule. Whenever an instruction can become a type, a lint rule or a test, it should.

An example from this site: the English URLs of the articles are declared by hand in a routing module, separately from the content, for performance reasons. The risk is obvious: an article published without its route, or a route pointing to a deleted article. Rather than an instruction saying “remember to update both”, a test compares the two lists and breaks CI on the slightest mismatch.

Specs before prompts

For any feature beyond an hour of work, the sequence is: written specification, reviewed by a human, then implementation by the agent, then review of the diff against the specification. The specification holds the acceptance criteria, the test plan and the known pitfalls of the existing code. The implementation prompt derives from it; it does not replace it.

Review changes nature: the question is no longer “do I like this code?” but “does it do what was decided, and nothing else?”. A question that can be answered quickly and well.

Treat docs as code

With an agent, documentation is no longer a courtesy to future hires: it is an input to the system. Wrong docs produce wrong code, confidently. On this site, outdated security documentation steered an entire framing towards a constraint that no longer existed. The fix is simple and rarely applied: the PR checklist asks for the docs the change touches to be updated, and the reviewer checks it.

Keep humans in the right places

The agent can propose anything; it should not execute everything. Production releases, data migrations, deletions, sending to third parties: these actions stay approved by a person. The same holds when AI is inside the product. Novera Signal, an agent in production, drafts every prospecting message but sends none on its own: it is a written architecture decision, recorded in an ADR, not a setting.

Where to start

1. Pick a single, representative repository rather than rolling out everywhere at once.
2. Write its CLAUDE.md with the team, settling contradictory conventions.
3. Wire everything that can be into CI: types, lint, tests, build.
4. Pilot on a real feature, specification included, and review the result together.
5. Extend to other repositories what worked, and only that.

It is the method I apply to my own products, described in detail in how I build a SaaS solo with Claude Code.