I use Claude to generate code every day. I also think most AI-generated code is garbage unless you build guardrails around it. These two statements are not contradictory. The model is capable. What it lacks is context: your repo's conventions, your error handling patterns, the things your team simply does not do. Without that context, the output looks right and fails quietly. With it, the same model becomes genuinely useful.
Why generic assistants fail
A generic coding assistant knows programming in general and your codebase not at all. It does not know how your team structures modules, how errors are handled and logged, which patterns are banned and why, or how tests are written in this repo. So it guesses, and its guesses are shaped by the most common patterns in its training data, which are rarely your patterns.
The failure modes are silent, which is what makes them dangerous. The code compiles. The tests the model wrote for it pass, because the model wrote tests that match its own assumptions. What is wrong is structural: the wrong abstraction, an ignored edge case, an API that almost exists but does not, error handling that swallows the exact failure you will need to debug at 2 AM. A human reviewer has to re-derive all of this from scratch, which is slower than writing the code in the first place.
This is why I never accept AI output blind. Every AI-generated diff on my team gets a deep-dive human review. Not a skim. A review where the reviewer can explain the change afterward. If I cannot explain a diff, it does not ship, no matter who or what wrote it.
The cognitive debt problem
The industry has started naming this. Researcher Margaret-Anne Storey coined the term "cognitive debt" for what happens when developers ship working software they do not genuinely understand or know how to maintain. Unlike technical debt, which lives in the code, cognitive debt lives in people: it accumulates when a team loses its collective understanding of the system it is building.
The numbers behind the concern are stark. CodeRabbit's 2025 data found AI-submitted pull requests averaged 10.83 issues flagged in review versus 6.45 for human-submitted PRs, roughly 1.7 times as many. A Sonar survey from January 2026 found 96 percent of developers do not fully trust AI-generated code to be functionally correct, yet only 48 percent say they check every time before committing. And in September 2026, engineering operations roundups were reporting teams restructuring code reviews around cognitive debt explicitly: small code-owner pods, automated checks handling routine edits, human reviewers reserved strictly for architecture.
The pattern to avoid is the fully automated pipeline: AI generates, AI reviews, human merges with minimal engagement. Nothing in that loop builds understanding. The team ends up responsible for a system whose design decisions were made by nobody.
The SKILLS.md pattern
The single highest-value practice we adopted is repo-specific context files. In our repos these are SKILLS.md files, checked in alongside the code, that encode how we actually work:
# Repo conventions
## Module structure
- One responsibility per module: `handlers/` for HTTP,
`services/` for logic, `store/` for persistence.
- No business logic in handlers.
## Errors
- Wrap with context at every boundary:
`fmt.Errorf("store: get user: %w", err)`.
- Never swallow errors. Log with fields, then return.
## Banned patterns
- No global mutable state.
- No `init()` functions with side effects.
- No new dependencies without a note in the PR description.
## Tests
- Table-driven tests for all branching logic.
- Run `make check` before pushing: lint, vet, full test suite.
The file is concrete, specific, and enforced. It is not philosophy; it is the checklist the model consults before writing a line. And it is maintained like code: updated when conventions change, reviewed in pull requests, owned by the team.
What goes in a context file matters. Vague guidance ("write clean code") is useless; the model already tries to do that. What works is the specific and the local: the exact error-wrapping format, the directory layout, the commands to run, the patterns this team banned after learning the hard way. Every entry should answer a question the model would otherwise guess at.
The file also needs an owner and a habit. Ours gets updated whenever a reviewer catches the model making the same mistake twice: that mistake becomes a new line in SKILLS.md, and the next session does not repeat it. Over a few months the file converges on the team's real conventions, including the ones nobody bothered to write down before the model forced the issue. Treating the context file as living documentation, reviewed in pull requests like any other code, is what keeps it accurate instead of letting it rot into wishful thinking.
Mandatory review gates
Context files improve the draft. Review gates decide what ships. Our rule is simple: AI output is a draft, and a human signs every commit. The review of an AI-generated diff is a deep dive, and it checks specific things:
- Edge cases the model skipped. Models are optimistic; they handle the happy path thoroughly and the boundaries thinly.
- Error paths. Does the failure mode produce a debuggable error, or does it vanish into a generic 500?
- Hidden assumptions. What did the model assume about the caller, the data shape, the concurrency model? Are those assumptions true here?
- Respect for existing abstractions. Does the change extend the current design, or does it bolt on a parallel one?
- Tests that actually test. A test asserting the model's own output is not a test. Check what the test would catch if the implementation were wrong.
No rubber stamps. The cultural rule matters more than the checklist: if the reviewer cannot explain the change, it does not merge. This is the direct antidote to cognitive debt. Understanding is verified at the gate, every time.
System Architecture
It helps to see this workflow as a system rather than a set of habits. There are four stages and one feedback loop.
+------------------+ +------------------+ +------------------+
| Developer |---->| Prompt assembly |---->| AI agent |
| task | | task + SKILLS.md | | Claude |
+------------------+ +------------------+ +--------+---------+
|
v
+------------------+
| Draft diff |
+--------+---------+
|
v
+------------------+
| Automated gates |
| lint vet tests |
+--------+---------+
|
v
+------------------+
| Human review |
| must explain |
+--------+---------+
|
+-----------------+-----------------+
| |
v v
+-----------+ +------------------+
| Merge | | SKILLS.md update |
+-----------+ +------------------+
- Prompt assembly. The developer's task is combined with the repo's SKILLS.md and whatever structural map the tooling provides. This is the highest-leverage stage: everything downstream is bounded by context quality, and no amount of review fixes a draft built on wrong assumptions.
- Agent execution. The model produces a draft diff with bounded tools: read files, edit code, run commands. It does not push, merge, or touch production. The sandbox is part of the architecture, not an afterthought.
- Automated gates. Deterministic checks that cost almost nothing: lint, vet, the full test suite, the build. These catch mechanical failures so human reviewers do not spend expensive attention on them.
- Human review. The expensive, non-substitutable gate. The reviewer must be able to explain the diff afterward. This is where cognitive debt is either prevented or accumulated, one merge at a time.
The feedback loop is what makes the system improve instead of merely repeating. When review catches the model making the same mistake twice, that mistake becomes a new rule in SKILLS.md, and the next session does not repeat it. Note what is deliberately absent: there is no auto-merge path, and no AI reviewer acts as the final gate. The human signature on the merge is the load-bearing part of the design. Remove it and you have a very fast way to produce code nobody understands.
Scalability
Load in this workflow means engineers times repos times concurrent agent sessions times context size, and the stages scale very differently.
At roughly 10x, say a team growing from five to fifty, the context file is the first thing that breaks if it is a single global document. Federate it: a small org-wide base file for universal rules, per-repo SKILLS.md files for local conventions, and directory-level overrides only where a subtree genuinely differs. Keep each file tight, because every rule costs tokens on every agent invocation. A 400-line context file nobody prunes is a tax on every session. The test for whether a rule earns its keep is empirical: acceptance rates and repeat-mistake recurrence.
The binding constraint at any size is human review bandwidth. Review is serial. It does not scale with the number of agents you deploy, and adding agent sessions without adding review capacity does not increase throughput; it grows a queue of unreviewed diffs, which is worse than not generating them. The levers are unglamorous: automated gates absorb all routine verification so humans only see diffs that passed, review pods align to code areas so context stays warm, and review SLAs with escalation keep diffs from rotting in the queue.
At roughly 100x, org scale, add machinery. CI validation that SKILLS.md files are well-formed and fresh (flag files untouched for months while the repo changed around them). Golden-task evals per repo that run whenever the model version changes, to catch silent regressions in output quality. Per-team token budgets with alerts, because cost without attribution becomes a surprise. And merge-queue discipline, because parallel agents working the same area produce conflicting diffs that need serialization and rebasing like any other concurrent edits.
For queueing and backpressure, treat agent sessions like any other queued work. Cap concurrent sessions per repo. When the review queue passes a threshold, throttle new agent task submissions instead of letting unreviewed work pile up. Backpressure here is a feature, not a limitation: an agent fleet that outruns its reviewers is a defect generator with good marketing.
Security Considerations
An agent that can read your repo, edit files, and run commands is a privileged actor. Design for that.
Isolation first. Run agents in sandboxes or containers with no network egress by default and filesystem access limited to the working repo. The agent does not need production credentials, customer data, or your SSH keys, so it should not be able to reach them. CI identities used by agent sessions get short-lived, narrowly scoped tokens, never a personal access token with broad permissions.
Secrets discipline. SKILLS.md and prompts must never contain secrets, and secret scanning should run on every agent-generated diff, not just human-written ones. Instruct the agent never to print environment variables or config values into logs or comments. Assume anything the agent can read can end up in a prompt log somewhere, and scope its reads accordingly.
The attack surface most teams miss is prompt injection through repo content. Issue bodies, PR comments, code comments, and vendored files are all untrusted input to the agent. A crafted comment can carry instructions: exfiltrate a file, weaken a check, add a dependency. Related to this, a poisoned SKILLS.md change in a PR can quietly rewrite the rules every future session follows, so context file changes deserve CODEOWNERS protection and the same deep review as security-sensitive code. Other vectors worth naming: the agent suggesting a typosquatted or malicious dependency (which is why new dependencies get a note in the PR description), and tool-use exfiltration, where an agent with network access and file read access becomes a data pipeline out of your network.
Mitigations, concretely: sandbox without egress, an allowlist of tools the agent may invoke, human approval required for irreversible or external actions, an audit log of every tool call the agent makes, and TLS plus at-rest encryption for stored prompts and diffs with a defined retention policy. None of this is exotic. It is the same least-privilege posture you apply to any service account, applied to one that writes code.
Production Checklist
If this workflow is load-bearing, operate it like production.
- Monitoring. Track diff acceptance rate (merged without major rework), median review cycles per AI diff, post-merge defect rate for AI-generated versus human-written diffs, SKILLS.md freshness (days since the last meaningful update), and token spend per team per week. Acceptance rate is the canary: a sustained drop means stale context, a model regression, or reviewers going through the motions.
- Alerting. Alert on acceptance-rate drops, review SLA breaches, anomalous agent tool calls (network attempts from a sandboxed session, reads outside the repo), and secret-scan hits on agent diffs.
- Runbooks. Write them before you need them. Model version change: run the golden-task eval, pin the previous version on regression. Suspected poisoned context file: revert the file, audit every diff merged since the change. Agent outage: fall back to manual development, since SKILLS.md doubles as human documentation the process degrades to slower, not to broken. Prompt injection incident: revoke session tokens, audit the session's tool calls and diffs.
- Failure modes. Know yours in advance: context rot (the file describes last year's conventions), reviewer fatigue (the deep-dive rule quietly becomes a skim), model drift after an update, CI exhaustion from agent-generated test runs, and parallel agents producing conflicting diffs on the same code.
- Graceful degradation. The test of the whole design: turn the agent off and the workflow should still function. The gates, the review standard, and the context file are the system. The agent is an accelerator inside it, not a dependency of it.
What actually changed in practice
Honest accounting, because the hype deserves pushback. AI made us faster at boilerplate, scaffolding, test skeletons, exploring unfamiliar APIs, and translating well-understood patterns into code. It did not make us faster at design decisions, novel problems, debugging production incidents, or anything where the repo's history and constraints matter more than general programming knowledge.
The net effect is positive, but only because of the guardrails. Without the context files, output quality drops enough that review takes longer than writing. Without mandatory review, plausible-looking defects accumulate into the kind of debt you discover during incidents. The workflow is: context in, draft out, human decides. Skip any step and the math stops working.
A few tradeoffs deserve plain statements, because they are the questions that come up every time.
Context size versus cost. Every line in SKILLS.md is tokens on every invocation. Past a point, more context stops improving output and starts costing money and attention. The test is empirical: if removing a rule changes neither acceptance rates nor repeat-mistake recurrence, the rule was not earning its tokens. Prune on evidence, not on feeling.
Review depth versus velocity. Deep-diving every diff does not scale linearly, and pretending it does produces the skim you were trying to avoid. The honest answer is risk-based review: trivial, well-covered diffs get a lighter pass once the automated gates clear them, while anything touching architecture, concurrency, security boundaries, or money gets the full deep dive. The rule that the reviewer must be able to explain the diff still applies at every tier; what changes is how long that takes to verify.
Agent autonomy versus control. More autonomy (the agent plans, executes, and tests multi-step work on its own) yields bigger wins and bigger failure modes. The failure mode is not only bad code; it is a diff so large no human can hold it in their head, which reintroduces cognitive debt through the back door. Keep agent work scoped to reviewable units. If the diff is too big to explain, it is too big to merge, no matter who wrote it.
And one failure scenario to plan for: the quarter nobody updates SKILLS.md. Conventions drift, the file goes stale, acceptance rates sag, reviewers start fixing the same issues by hand instead of codifying them, and within months the file is decorative. The fix is ownership plus a forcing function: a named owner per file and a CI check that flags staleness. Living documentation dies without a gardener.
Start here
If your team is adopting AI coding tools and has none of this in place, the order matters:
- Write the context file. One file, concrete conventions, checked into the repo. Update it as you learn what the model gets wrong.
- Enforce real review. The reviewer must be able to explain the diff. Measure review depth, not PR count.
- Measure shipped quality, not generated volume. Lines generated is a vanity metric. Defect rate, review cycles, and time-to-understand are the ones that matter.
Generic assistants are a starting point, not a workflow. The teams getting real value from AI coding tools are the ones that wrapped the model in their own context and their own standards. The model does the typing. The team still does the engineering.