Agentic Coding Discipline

Operating procedure for long or autonomous coding sessions, distilled from Claude Code's living best-practices doc. Core premise: the context window is the most important resource to manage — it holds every message, file read, and command output, and LLM performance degrades as it fills. Every rule below either closes a verification loop so mistakes don't wait for a human, or protects context so quality doesn't decay mid-session. Mechanisms marked [CC] are Claude-Code-specific; the principles generalize to any coding agent.

When to use

• Starting any coding task expected to span multiple files, multiple turns, or unattended time.
• Setting up a repo or environment for agent work (CLAUDE.md, permissions, hooks, verification scripts).
• Batch/migration work across many files, or coordinating parallel sessions.
• Mid-session symptoms: repeated corrections on the same issue, context filling with irrelevant reads, "looks done" claims without evidence.

Do NOT apply the full ceremony to trivial edits: for a typo fix, a log line, or a rename — anything whose diff you could describe in one sentence — skip planning and do it directly. Vague, exploratory prompts are also legitimate when the goal is to see how the problem gets interpreted before constraining it.

Rules

Verification loops

1. Never treat "looks done" as done — give yourself a check you can run. Without a runnable check, the human becomes the verification loop and every mistake waits to be noticed. A check is anything that returns a readable pass/fail signal: a test suite, a lint pass, a build's exit code, a script diffing output against a known-good fixture, or a browser screenshot checked against the target design.
2. Escalate how hard the check gates the stop, matching setup cost to how unattended the run is. (a) In one prompt: run the check and iterate in the same task. (b) Across a session [CC]: set it as a /goal condition — a separate evaluator re-checks after every turn until it holds. (c) Deterministic gate [CC]: a Stop hook runs the check as a script and blocks the turn from ending until it passes; after 8 consecutive blocks, Claude Code overrides the hook and ends the turn anyway. (d) Second opinion: a verification subagent in fresh context tries to refute the result, so the work is not graded by the agent that produced it.
3. Show evidence, not assertions. Report the test output, the exact command run and what it returned, or a screenshot. Evidence is quicker to review than verification is to re-run, and it covers sessions that ran unattended.
4. Fix root causes, not symptoms. When a build fails, address the cause and verify the build succeeds — never suppress the error.
5. Before counting unattended work as done, run an adversarial review in a fresh context. Because the reviewer gets only the diff plus the criteria — never the reasoning behind the change — it judges the result on its own merits. Check the diff against the plan: every requirement implemented, listed edge cases tested, nothing outside scope changed. [CC] the bundled /code-review skill does the correctness pass in a fresh subagent.
6. Constrain the reviewer. Ask a reviewer to find gaps and it will produce some even when the work is sound; chasing every finding produces over-engineering (extra abstraction, defensive code, tests for impossible cases). Instruct it to flag only gaps affecting correctness or stated requirements — "Report gaps, not style preferences" — and treat the rest as optional.

Explore, plan, code, commit

7. Separate research and planning from implementation to avoid solving the wrong problem. Four phases: Explore (read files, no changes — [CC] plan mode via Shift+Tab or claude --permission-mode plan), Plan (write a detailed implementation plan; [CC] Ctrl+G opens it for human editing), Implement (code, verifying against the plan), Commit (descriptive message, open a PR).
8. Plan proportionally. Planning pays when the approach is uncertain, the change spans multiple files, or the code is unfamiliar. If the diff fits in one sentence, skip the plan — planning adds overhead.
9. Demand or supply specific context. Scope the task (which file, which scenario, testing preferences), point to sources (e.g. git history for "why is this API weird"), reference an existing pattern file to imitate, and describe bugs as symptom + likely location + what "fixed" looks like (write a failing test that reproduces the issue, then fix it).
10. For larger features, interview before building. Use a question tool ([CC] AskUserQuestion) to dig into implementation, UI/UX, edge cases, and tradeoffs; write a complete spec to SPEC.md; then execute in a fresh session with clean context. The most useful specs stand alone: they name the affected files and interfaces, mark what is out of scope, and close with an end-to-end verification step.

CLAUDE.md hygiene

11. Keep the persistent-memory file (CLAUDE.md) short and human-readable — it loads every session. Include: bash commands the agent can't guess, style rules that differ from defaults, testing instructions and preferred runners, repo etiquette (branch naming, PR conventions), project-specific architectural decisions, required env vars, non-obvious gotchas. Exclude: anything inferable from code, standard conventions, detailed API docs (link instead), frequently-changing info, file-by-file codebase descriptions, self-evident advice like "write clean code".
12. Apply the pruning test to each line: "Would removing this cause Claude to make mistakes?" (best-practices doc). If not, cut it. An overgrown file buries the rules that matter, and the agent starts ignoring them. If a rule keeps being violated, the file is probably too long and the rule is lost; tune adherence with emphasis ("IMPORTANT", "YOU MUST") or convert the rule to a hook.
13. Treat CLAUDE.md like code: check it into git, review it when things go wrong, prune regularly, and test changes by observing whether behavior shifts. [CC] /init generates a starter; /context confirms it loaded; @path/to/import pulls in other files; placements: ~/.claude/CLAUDE.md (all sessions), ./CLAUDE.md (shared), ./CLAUDE.local.md (gitignored personal), parent dirs for monorepos, child dirs loaded on demand.
14. Put sometimes-relevant knowledge in skills, not CLAUDE.md — skills load on demand without bloating every conversation. [CC] SKILL.md in .claude/skills/; set disable-model-invocation: true on side-effectful workflows meant for manual triggering.

Permissions and sandboxing

15. Pick the interruption-reduction mechanism deliberately — after the tenth approval a human is clicking through, not reviewing. Three options [CC]: auto mode (--permission-mode auto — a separate classifier blocks only risky actions: scope escalation, unknown infrastructure, hostile-content-driven actions), /permissions allowlists for known-safe commands like npm run lint or git commit, and /sandbox for OS-level filesystem/network isolation.
16. Use hooks for actions that must happen every time with zero exceptions. Memory-file instructions are advisory; hooks are deterministic. [CC] configure in .claude/settings.json, browse with /hooks; e.g. run eslint after every file edit, or block writes to a migrations folder.
17. Prefer CLI tools (gh, aws, gcloud, sentry-cli) for external services — the most context-efficient integration, and authenticated (raw unauthenticated API calls hit rate limits). Learn unknown tools via --help before using them. Connect richer integrations via MCP servers.

Context management

18. Reset context between unrelated tasks ([CC] /clear). Long sessions with irrelevant context reduce performance.
19. After two failed corrections on the same issue, stop correcting. By then the context carries every failed approach. Clear it and restart with a prompt that bakes in what was learned — a fresh session with a better prompt almost always does better than a long one weighed down by corrections.
20. Compact with intent. [CC] /compact <instructions> (e.g. /compact Focus on the API changes); partial compaction via Esc+Esc//rewind → "Summarize from here" / "Summarize up to here"; add a CLAUDE.md rule like "When compacting, always preserve the full list of modified files and any test commands" so critical context survives; /btw for side questions that shouldn't enter history.
21. Delegate investigation to subagents. Research reads many files; run it in a separate context that reports back a summary, keeping the main conversation clean for implementation. [CC] define specialists in .claude/agents/ with their own tools allowlist.
22. Use checkpoints to make risk cheap. [CC] every prompt creates a checkpoint; /rewind (or Esc+Esc) restores conversation, code, or both — so try the risky approach and rewind if it fails. Caveat: checkpoints only track the agent's file-editing tools, not Bash or external changes — not a git replacement. Name persistent sessions (/rename, claude --continue, claude --resume) and treat them like branches per workstream.

Fan-out and agent teams

23. For batch work, fan out with scoped permissions. [CC] pattern: (1) generate a task list to a file (files.txt); (2) loop claude -p "Migrate $file ... Return OK or FAIL." --allowedTools "Edit,Bash(git commit *)"; (3) test on the first 2-3 files, refine the prompt from what goes wrong, then run at scale. --allowedTools matters when running unattended. Output formats: --output-format json (single object with a result field) or stream-json --verbose (one JSON object per line); --no-session-persistence skips saving; in -p runs auto mode aborts if the classifier repeatedly blocks, since no user can approve.
24. Parallelize with isolation. Run sessions in git worktrees (or desktop/cloud sessions, or agent teams with shared tasks and a team lead) so edits don't collide.
25. Exploit fresh context for quality, not just throughput. A Writer/Reviewer split across two sessions improves review because the reviewer isn't biased toward code it just wrote; similarly, have one session write tests and another write code to pass them.

Checklist

Before starting:

• Is there a runnable check for this task (tests / build / lint / diff script / screenshot)? If not, create one or get criteria.
• Task > one-sentence diff? Then explore first, write a plan, get it confirmed before coding.
• Unattended run? Gate the stop: /goal condition or Stop hook [CC], plus scoped --allowedTools.
• Prompt names specific files, constraints, and an example pattern to follow.

During:

• Delegate broad codebase research to a subagent; keep main context for implementation.
• Two corrections failed on the same issue → clear context, restart with an improved prompt.
• Context filling with unrelated material → /clear between tasks, /compact <instructions> within one.

Before claiming done:

• Check ran and passed; evidence captured (test output, command + result, screenshot).
• Root cause fixed, not symptom suppressed.
• Fresh-context adversarial review of the diff against the plan: requirements implemented, edge cases tested, nothing out of scope changed; only correctness/requirement gaps acted on.
• Committed with a descriptive message; CLAUDE.md updated only if a durable, broadly-applicable lesson emerged (then pruned by the "would removing this cause mistakes?" test).

Anti-patterns

• The kitchen sink session: mixing unrelated tasks in one context. Fix: clear between tasks.
• Correcting over and over: each failed approach lingers in context. Fix: after two failed corrections, clear and write a better initial prompt.
• The over-specified CLAUDE.md: important rules lost in noise, agent ignores half the file. Fix: ruthlessly prune; convert must-happen rules to hooks.
• The trust-then-verify gap: plausible-looking implementation with unhandled edge cases. Fix: always verify with tests/scripts/screenshots — what can't be verified shouldn't ship.
• The infinite exploration: unscoped "investigate X" reads hundreds of files and fills context. Fix: scope narrowly or delegate to a subagent.
• Grading your own work: the session that wrote the code declaring it correct. Fix: fresh-context reviewer given only the diff and criteria.
• Chasing every reviewer finding: over-engineering from a reviewer that was asked to find gaps and therefore found some. Fix: act only on correctness/requirement gaps.

Source

• Claude Code: Best practices (living doc) — https://code.claude.com/docs/en/best-practices — 2026 (living)

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.