Good practices

Practices that hold across teams shipping AI-assisted code at pace. Each one is operationalised by a command.

1. Negative-space documentation

Document what was not done and why. Future agents stop re-suggesting rejected paths. The Reconsider if line keeps the rejection live.

→ adr

2. Defensive commits

Commit before any large refactor. Long agent sessions touch dozens of files; without a checkpoint, partial rollback is painful.

→ plan includes a checkpoint step.

3. Interface-first development

Define types, signatures, API contract before implementation. The agent fills a defined shape well; it chooses shapes poorly.

4. Verification-driven logic

Every task ships with a verification command. The agent iterates until verification passes; you review the design, not the syntax.

→ verify

5. Plan Mode discipline

The plan is reviewed as a contract before any code is written.

→ plan

6. Standardised initialisation

Every new repo starts with the same scaffolding. One command, so it is not skipped.

→ init

7. Delta updates over rewrites

When a convention changes, add the new one with a date and mark the old one deprecated with a reason. Rewrites lose the why.

→ document

8. Scoped rules

Rules apply where they make sense. Frontend rules in frontend files; database rules in migrations. Nothing global unless really global.

→ scope

9. Least-privilege tooling

Agent access partitioned. Read-only context is one server; write actions another. Destructive actions require human approval.

→ mcp

10. Measure conformity

The metric worth tracking: percentage of generated code passing the project's own checks without modification. Below 80% means the context is not communicating.

→ audit

11. Split-file architecture

A single CLAUDE.md that grows becomes a dumping ground. AGENTS.md stays canonical, hand-edited, capped around 80 lines. CLAUDE.md is a symlink. Per-harness pointer files for Cursor, Copilot, Windsurf are five lines each. Overflow goes to docs/agents/<area>.md.

AGENTS.md                          ← canonical, lean (~80 lines)
CLAUDE.md -> AGENTS.md             ← symlink
.cursor/rules/main.mdc             ← 5-line pointer
.github/copilot-instructions.md    ← 5-line pointer
.windsurf/rules/main.md            ← 5-line pointer

docs/agents/                       ← neutral overflow
  frontend.md
  backend.md

.claude/rules/                     ← optional Claude-Code-only auto-load

.claude/rules/ is a Claude Code-specific feature: auto-loads every file in filename-sort order. Use it only when you want that behaviour; for harness-agnostic overflow use docs/agents/.

12. Three-tier boundary layout

The old "out-of-bounds" framing is one bucket. Real projects have three:

• Always. Things the agent does without asking (run fast verification, follow Non-negotiables).
• Ask first. Things the agent proposes (multi-file changes, dependency additions, public-API edits).
• Never. Forbidden paths or destructive actions.

State all three explicitly in AGENTS.md. "Ask first" is the tier most often missing, and the one that prevents the most scope creep.

13. HTML preservation tags

For code that must not be edited (legacy compromises, hot paths, compatibility shims), wrap with markers:

<!-- CE:PRESERVE: legacy auth flow, removed in v3. Do not modernize. -->
function legacyHash(input: string): string {
  // ...
}
<!-- /CE:PRESERVE -->

Always include a one-line reason. Use sparingly; a growing pile is a smell. Audit the count in code review.