Best Practices Checklist: Production Claude Code and SDK

Overview: Why production discipline matters

Claude Code agents are autonomous and powerful. Without discipline, they become:

• Context-bloated: CLAUDE.md grows to hundreds of lines; important rules get lost
• Permission-loose: Too many auto-approved tools; agents do things you didn't intend
• Over-orchestrated: Subagents spawning subagents; skills calling hooks; MCP calling workflows
• Cost-out-of-control: Token usage triples because layers of indirection duplicate reasoning
• Change-unreviewed: Agent changes (new skills, new subagents, new CLAUDE.md rules) ship without code review

This checklist ensures your team uses Claude Code effectively at scale.

CLAUDE.md hygiene

Principle: Every line in CLAUDE.md should earn its place. If removing it causes Claude to make mistakes, keep it. Otherwise, delete it.

✓ Checklist: CLAUDE.md

| Item | How to verify | Guidance | | :--- | :--- | :--- | | Length < 500 lines | wc -l .claude/CLAUDE.md | If longer, you're mixing concerns. Split into multiple files or create skills. | | No API documentation | Grep for "endpoint," "parameter," "response" | Link to your API docs instead. Don't copy/paste docs. | | No tutorial or explanation | Grep for "This is how," "explain," "tutorial" | Link to onboarding docs. Keep CLAUDE.md facts, not teaching. | | No file-by-file descriptions | Check for "src/foo/ contains," "src/bar/ is for" | Trust Claude to explore. If structure is non-obvious, document it once at the top. | | Has bash commands Claude can't guess | Verify all commands are project-specific | Include only what's unique: npm run test is obvious; npm run test:integration -- --reporter json is not. | | Has code style rules that differ from norms | Check for convention overrides | Include only if they're non-standard: "use snake_case for environment variables" yes; "use 2-space indents" no (obvious). | | Has architectural decisions | List key constraints and trade-offs | Important: "Session tokens are stored in httpOnly cookies for security"; not important: "We use Express instead of Hapi." | | Checked into git | git log .claude/CLAUDE.md | CLAUDE.md is project knowledge; it should have history and be reviewed. | | Reviewed in pull requests | Check if PR reviewers comment on CLAUDE.md changes | Treat CLAUDE.md changes like code changes: approve them explicitly. | | Version-pinned if it references tools | Verify all tool/library versions are pinned | If you mention "Node.js 18+," later say "tested with Node 20.x and 21.x." |

Red flags:

• CLAUDE.md is > 1000 lines
• CLAUDE.md is never updated (stale)
• CLAUDE.md is never reviewed (added by one person, no git history)
• CLAUDE.md contradicts itself

Permission scoping and discipline

Principle: Pre-approve only what you trust. Everything else requires explicit approval or a permission rule.

✓ Checklist: Permissions

| Item | How to verify | Guidance | | :--- | :--- | :--- | | Session starts with default mode | Check /config or .claude/settings.json; "permissionMode" should not default to bypassPermissions | Default to acceptEdits or auto. Never default to bypassPermissions. | | allowedTools list is explicit | Check ~/.claude/settings.json or per-session setup | List only tools you're confident about. Don't use allowedTools: [] (denies everything) unless you have a callback. | | Destructive commands are restricted | Test: try rm -rf . and confirm it's blocked | Use permission rules to block: "command_pattern": "rm.*-rf.*", "policy": "block" | | Git push requires explicit rule or approval | Check permission rules for git push; it should not be in allowedTools | Require approval for git push to main/master. Allow for feature branches if prudent. | | Secrets are never logged | Grep .claude/ for API keys, credentials | If secrets appear in logs, revoke them immediately. | | Permission rules are versioned | git log .claude/settings.json or your policy file | Permission rules are security policy; track changes. | | MCP tool access is scoped | Check mcpServers config; list only needed servers | Don't enable all MCP servers. Enable only ones you're actually using. | | Non-interactive mode (-p) uses strict permissions | Test: run claude -p "prompt" --permission-mode auto | Unattended agents should use auto or dontAsk, never bypassPermissions. |

Red flags:

• Permission rules never reviewed
• bypassPermissions is the default
• Secrets appear in agent logs
• Git push is in allowedTools

Code review discipline

Principle: Agent changes (CLAUDE.md, skills, subagents, hooks) are code. Treat them as such.

✓ Checklist: Review and approval

| Item | How to verify | Guidance | | :--- | :--- | :--- | | CLAUDE.md changes reviewed in PR | Check PR comments on CLAUDE.md diffs | Treat like code. Ask: does this help or hurt clarity? Does it encode wisdom or noise? | | New subagents reviewed before deploy | Check .claude/agents/*.md in PR history | Review the prompt, tools, and description. Does it match the use case? Is the description clear? | | New skills reviewed before deploy | Check .claude/skills/*/SKILL.md in PR history | Review the steps. Are they safe? Do they handle errors? Can they be misused? | | Hooks reviewed for side effects | Check .claude/hooks/ or hook configs | Hooks run automatically; they must be correct. Code review them carefully. | | MCP server additions reviewed | Check mcpServers config changes | New MCP servers grant new capabilities. Approve carefully. | | Large CLAUDE.md changes have justification | PR description explains why it was added | If you're adding 50 lines, explain why in the PR. | | Agent changes have linked context | PR comments reference related issues, docs, or decisions | Context helps reviewers and future maintainers. |

Red flags:

• CLAUDE.md changes ship without PR review
• New skills appear without description of what they do
• Hooks are auto-merged (they're risky and deserve careful review)
• MCP servers are enabled for "experimental" reasons without removal dates

Cost management

Principle: Every token costs money. Monitor usage; optimize when high.

✓ Checklist: Cost control

| Item | How to verify | Guidance | | :--- | :--- | :--- | | Monitor per-session token usage | Run claude --analyze-cost or check usage dashboards | Identify expensive sessions. Ask: why did this use 100k tokens? | | Subagents use appropriate models | Check subagent model fields in .claude/agents/ | Use haiku for reading, sonnet for reasoning, opus for hard problems. Don't default to opus everywhere. | | Context windows are compacted | Check if /compact or /clear are used to manage session size | Long sessions fill up. Compact when approaching limits to summarize and free space. | | Expensive tasks are batched | Check if similar queries are run in one session, not separately | Running 3 migrations in one session (3× context reuse) is cheaper than 3 separate sessions. | | Workflows are sized appropriately | Check workflow max_turns and expected agent count | Set max_turns to prevent runaway loops. Check /workflows progress view to spot runaway cost. | | Read-only analysis uses read-only tools | Check subagents with tools: Read, Grep, Glob | Read-only agents reason faster (simpler logic). | | Non-essential tools are not enabled | Check allowedTools and mcpServers; disable unused ones | Every extra tool adds reasoning overhead. Enable only what you need. |

Red flags:

• One session uses > 500k tokens with no explanation
• All subagents use opus model
• Workflows regularly run > 50 agents (expected cost > $50)
• Sessions are never compacted; context always grows

Common mistake

Over-parameterizing CLAUDE.md, skills, and hooks. Teams add "just one more" rule, "just one more" subagent, "just one more" MCP server. After months, the system is unmaintainable and slower.

Instead: Before adding anything, ask:

• Does this solve a real problem, or just a hypothetical one?
• Is this better than an alternative (e.g., skill vs. hook)?
• Can we remove something else to keep complexity flat?
• Have we reviewed and approved this change?

Simpler systems are faster, cheaper, and easier to debug. Resist featuritis.