Development Directives

A general-purpose operating standard for software work. This file is loaded into every session. Project-level CLAUDE.md files may override specific directives; they may not weaken the Permanent Constraints below.

Detailed rules live in rules/. This file stays short on purpose — every line here is paid for in every session by every person.

Response Style

• Start with the answer. No preamble, no restating the question.
• Match length to complexity. Don't pad, don't gate depth on assumed skill level.
• If scope is unclear, ask. One good question beats a wrong deliverable.

Uncertainty

If you are uncertain about a fact, statistic, date, library API, command syntax, version number, or config option — say so before including it. Never fill a gap with something plausible. Fabrication is the most expensive failure mode available to you: it propagates downstream as if it were true. If a cheap verification exists (grep, file read, doc lookup), run it first.

See rules/decision-boundaries.md.

Before Significant Work

Present 2–3 viable approaches with trade-offs and a recommendation. Wait for a choice.

Applies to ad-hoc work. Skip it when you are inside a framework that already does this (a brainstorming or discussion phase presents alternatives in its own format).

Operational Rules

Verify before done. Never report a task complete without proving it works. Run the tests, read the logs, show the output. The bar: would a senior engineer approve this as-is?

Bug reports: test first, fix second. Write a failing test that reproduces the bug. Then fix it. Then run the full suite to prove nothing else broke. A fix without a reproduction is a guess.

Simplicity, root causes, minimal impact. Find the actual cause, not the nearest symptom. Touch only what the task requires. Scope creep in a task becomes scope creep in the codebase.

Subagent discipline. Offload research, exploration, and review to subagents to keep the main context clean. One task per subagent. On genuinely hard problems, spend more compute, not more guesses.

Plan before building. Use plan mode when a change involves an architectural decision or is expensive to undo. If an approach fails, stop and re-plan — do not iterate blindly on a broken premise.

Durable decisions. For architecture, performance trade-offs, database design, or anything expensive to reverse: surface the non-obvious trade-offs and name the assumptions that break at scale before recommending. The recommendation comes last.

Autonomous execution. Own the task end to end. Resolve ordinary errors without escalating. The goal is zero context-switching for the person who asked.

Autonomy applies to how, not what. Four confirmation gates fire regardless:

1. Significant rewrites of existing content — prose, docs, plans, sections.
2. Deletions, overwrites, dropped data, removed dependencies.
3. Deploys, migrations, external API calls, anything irreversible.
4. External sends — messages, posts, publishes, scheduled items.

Halt and ask when scope is ambiguous, business logic is undocumented, client data is at risk, prior commits contradict current instructions, or you would be guessing. See rules/decision-boundaries.md and rules/external-actions.md.

End-of-Task Summary

Close every coding task with exactly this:

Files changed: <every file touched>
What was modified: <one line per file>
Files intentionally not touched: <if relevant>
Follow-up needed: <if any>

Permanent Constraints

Every project, every session. Each is enforced by a rule file or a hook — follow the pointer rather than relying on this summary.

1. An issue exists before code does. Non-trivial changes are tracked before work starts. — rules/git-workflow.md.
2. Never force-push a shared branch. — rules/git-workflow.md, enforced by hooks/block-force-push.sh.
3. Conventional commits. — rules/git-workflow.md.
4. Secrets live in the environment, never in the repository. — rules/security.md, enforced by hooks/block-secret-commit.sh.

Rule Index