ai-exchange/docs/CLAUDE_template_autonomy_first.md

CLAUDE.md Template

Use this file as a starting CLAUDE.md for other repositories. Replace the placeholders and keep the execution rules unless the project needs stricter constraints.

---

CLAUDE.md

This file provides guidance to Claude Code when working in this repository.

Project Overview

• Project: <project name>
• Goal: <one-paragraph summary of what the repo does>
• Primary stack: <languages / runtime / framework / package manager>
• Main quality gate: <tests / typecheck / lint command that must pass>

Commands

# Install dependencies
<install command>

# Start dev mode
<dev command>

# Run tests
<test command>

# Run typecheck
<typecheck command>

# Run lint / format
<lint command>
<format command>

Collaboration Mode

Default to autonomy-first execution.

After the task is clear:

• proactively plan
• implement directly
• test and verify
• continue to the next concrete task without routine confirmation

Only stop and ask the user when you hit one of these:

1. an irreversible or high-blast-radius action
2. missing external credentials, services, or permissions
3. a real product decision with multiple valid directions
4. a blocker that cannot be resolved by reading code, running checks, or changing local files

Core Working Rules

1. Prefer product over status

Do not treat in_progress as progress. A task counts as progress only when there is a real artifact such as:

• edited code
• written docs
• created config
• migration file
• test result
• verification result

Rule:

• no artifact, no completion report

2. Break work into small executable tasks

For any non-trivial request, split the work into small tasks that each produce an inspectable result.

Good task examples:

• add repository method for loading candles
• create migration for sweep events
• wire runner script for session generation
• verify new script imports cleanly

Bad task examples:

• build the whole system
• finish the backend
• handle remaining work

3. Finish one concrete step, then immediately start the next

After completing a task:

• mark it complete
• summarize the concrete result briefly
• start the next highest-value unblocked task

Do not wait for permission between normal reversible steps.

4. Do not repeat the same blocker twice

If the same blocker appears twice without any new artifact or validation progress, stop looping. Immediately do one of:

• change the approach
• split the task smaller
• work on an adjacent unblocked dependency
• surface the true blocker clearly

Rule:

• never stay in a stale loop

5. Keep milestone updates short and factual

Progress updates should say:

• what was written or changed
• what was verified
• what is next

Avoid empty updates like:

• "working on it"
• "starting now"
• "continuing"

6. Parallelize only truly independent work

Use parallel work only when tasks do not share the same dependency chain.

Good parallel cases:

• two unrelated docs
• independent read-only inspections
• separate file checks

Bad parallel cases:

• multiple edits in the same file chain
• steps that depend on previous output
• intertwined refactors sharing context

7. Prefer shared foundations before upper layers

When building systems, usually work in this order unless the user says otherwise:

1. config
2. database / schema
3. core models
4. repositories
5. services
6. entry scripts / APIs
7. downstream features

This reduces rework.

8. Switch from docs to implementation as soon as the design is sufficient

Once the spec is clear enough, stop expanding docs and write the real files. Docs support implementation; they do not replace it.

Verification Rules

Before reporting a task complete:

• confirm the target file exists
• read back the important file sections you changed
• run the narrowest relevant check first
• prefer direct runnable validation over purely descriptive claims

Examples:

• compile the changed Python files
• run the changed script
• run a focused test file
• read the migration or config back after writing it

If verification is blocked by environment issues, say so explicitly and separate:

• code is ready
• environment is not ready

Risk Rules

Proceed without confirmation for local, reversible actions such as:

• reading files
• editing code
• creating normal source files
• running tests
• running local checks

Pause for confirmation before:

• deleting files or branches
• force push / history rewrite
• destructive database operations
• modifying shared infrastructure
• posting to external services
• actions visible to other people

If a safer reversible path exists, prefer it.

Communication Style

• be concise
• lead with the result
• reference files with path:line when useful
• do not over-explain routine steps
• report at milestone boundaries, not after every tiny action

Task Workflow

For substantial work:

1. create small tasks up front
2. set the current task to in_progress before starting
3. complete tasks immediately after finishing them
4. if a task grows too large, replace it with smaller tasks
5. keep progress moving; do not leave stale broad tasks hanging

Implementation Guardrails

• do not add features beyond the request
• do not refactor unrelated code while fixing a local issue
• do not add abstractions for one-off use
• do not add speculative compatibility layers
• validate user input and external boundaries, but do not over-defend impossible internal states

Recommended Repository-Specific Section

Add project-local facts below this line.

Architecture Notes

• <entrypoint>
• <main services>
• <important directories>

Quality Gates

• <must-pass command 1>
• <must-pass command 2>

Project-Specific Constraints

• <for example: strict typing, migration rules, no mocks, feature-flag requirements>

---

Maintainer Notes

This template is intentionally opinionated toward autonomy-first execution. If you want stricter supervision, replace the Collaboration Mode and Core Working Rules sections with project-specific alternatives.