Last article in this series on the audit of a Go authentication service. After covering security patterns, mTLS infrastructure, CQRS architecture, and audit methodology, one question remains: how do you document all this for AI agents that will touch the code after you?
The project's CLAUDE.md was 296 lines. After the audit, it's 142. Minus 52%. And the agent codes better than before.
The "document everything" reflex
The natural pattern: every time the agent makes a mistake, you add a line to CLAUDE.md. "Don't forget the dummy hash on login." "CSRF middleware must come after session-load." "CRLs are checked in two places."
Result: a file that grows monotonically, never cleaned up. Each addition is individually legitimate. But collectively, the signal-to-noise ratio drops with every line.
CLAUDE.md is an attention budget. Each line consumes context. If you put 296 lines, the agent gives as much weight to "the layout is in /cmd" (which it can deduce in 2 seconds with tree) as to "the CRL Number must be monotonically increasing" (a critical security invariant not deducible from code).
The deletion test
For each line in CLAUDE.md, one question:
If I delete this line and a senior dev reads the code, would they be missing something?
What fails the test (= deletable):
- Layout tree —
treegives it in 1 command - Tech stack —
go.modsays it - How to run tests —
Makefileorgo test ./... - Standard Go patterns — a senior dev knows them
- "Use context.Context everywhere" — that's the default Go convention
What passes the test (= keep):
- Invariants — "event-XOR-error on command handlers, never both"
- Gotchas — "CRL check happens in two places, handshake AND middleware"
- Non-obvious decisions — "PBES2 + KSP attribute instead of PBES1 for .p12 files"
- Security choices — "Argon2 dummy hash recomputed at boot with current params"
- Regression anchors — "do not remove the monotonic check on crl.Number"
The 5 categories that survive
After cleanup, the CLAUDE.md only contains 5 types of information:
1. Architectural invariants
Rules that, if violated, break system consistency:
## Invariants
- Command handler: event XOR error, never both
- Projector: all side-effects in a single TX, except logout (best-effort)
- Session: cert serial stamped at creation, verified on each request
2. Non-deducible gotchas
## Gotchas
- CRL check: VerifyConnection (handshake) + HTTP middleware (request-time)
Both are needed. Don't remove one without the other.
- CSRF middleware: AFTER session-load, BEFORE refresh-user. Order matters.
- Login timing: dummy hash MUST use the same params as the real hasher.
3. Security decisions
## Security decisions
- .p12: PBES2/AES-256 + MS KSP attribute (OID 1.3.6.1.4.1.311.17.1)
NO PBES1/3DES fallback, even if "it works on Windows".
- Lockout: same status code (401) for locked, wrong creds, unknown user.
- Audit log: login failures on unknown users = slog only, NO DB row.
4. Regression anchors
## Do not remove
- Test TestP12HasKSPAttribute: validates .p12 structure for Windows
- Test TestDummyHashUsesCurrentParams: prevents param bump regression
- CRL Number monotonic check: protects against rollback attack
- SNI == Host guard: protects against misdirected request
5. Trust boundaries
## Trust boundaries
- api.internal: mTLS required (serviceCAPool)
- admin.internal: mTLS required (adminCAPool, different CA)
- app.internal: no client cert (web users)
What we deleted
154 lines deleted. Here's what they contained:
- 42 lines of layout tree (
tree -L 2replaces them) - 28 lines of "how to do X" (the Makefile covers these)
- 31 lines of standard Go patterns ("use errgroup", "always defer Close()")
- 18 lines of stack/dependencies (readable in go.mod)
- 22 lines of naming conventions (deducible from existing code)
- 13 lines of CI documentation (readable in the pipeline YAML)
Before / after: the difference in practice
Before cleanup, the agent cited CLAUDE.md lines to justify its choices. The problem: it cited the wrong lines. "According to CLAUDE.md, the project structure is /cmd/server/main.go" — yes, thanks, that doesn't help me not break the CRL check.
After cleanup: fewer verbatim citations, more effective invariant compliance. The agent no longer says "according to CLAUDE.md". It applies the constraints because they're the only information available — not drowned in noise.
The counter-intuitive lesson: fewer instructions → better compliance.
CLAUDE.md vs AGENTS.md vs README
Separation of concerns applies to agent documentation too:
File
Audience
Content
CLAUDE.md
AI agent
What it needs to know to NOT break things
AGENTS.md
AI agent
What it needs to know to do things WELL (style, workflow)
README
Human
What a human needs to know to understand the project
Overlap between these files is documentation debt. If the same information is in CLAUDE.md and README, it will be updated in one and forgotten in the other. One source of truth per piece of information.
Conclusion
An effective CLAUDE.md doesn't tell the agent how to code. It tells the agent what it can't deduce from the code itself. Everything else is noise that dilutes the signal.
The security audit produced invariants, gotchas, and regression anchors. CLAUDE.md is the right place to document them — as long as you document only that. The deletion test is the filter: if a senior dev deduces the information in 5 seconds, it doesn't belong in CLAUDE.md.
This is the last article in the "auth2" series. In 9 articles, we went from a PKCS#12 container bug to audit methodology and documentation for AI agents. The common thread: every security pattern is simple on the surface. The complexity is in the implicit couplings — between container and provider, between timing and params, between handshake and middleware. Making these couplings explicit is the job.
