Repository And Capstone Baseline — Claude Code Guide

The starting baseline should be clean and reproducible

Start the capstone from a controlled point: repository, SPEC.md, CLAUDE.md, EVIDENCE.md, and one small next task. Check the baseline state first, then begin functional implementation.

A new project can start with git init, basic directories, and the first commit. An existing repository needs a clean tree and a separate working branch.

Git baseline and .gitignore

1. Check git status and confirm there are no unsaved changes.
2. Add the directory structure and starting documents.
3. Make sure .env files, dependencies, build output, logs, and caches are not tracked.
4. Review the file list before committing.
5. Create a separate baseline commit.
6. Record the state from which the first small task begins.

git status
git diff --stat
git ls-files

CLAUDE.md should be short and local

Permanent rules belong in CLAUDE.md, while hypotheses, ideas, and current results belong in SPEC.md, EVIDENCE.md, or separate working notes. Do not add secrets or unverified assumptions to the instructions.

• describe the purpose of the system;
• name the real commands for running and checking it;
• record the rules for making changes;
• prohibit actions that require separate approval;
• require the report to list changed files and completed checks.

Create EVIDENCE.md immediately

• what was requested from Claude;
• what useful result was obtained;
• which decisions the developer made;
• how the result was checked;
• which risks or questions remain open.

The first task should be small

1. Run the project locally.
2. Implement one happy path.
3. Add a smoke check.
4. Record the actual result in EVIDENCE.md.
5. Review the diff and update SPEC.md if needed.
6. Move to the next step only after checking the previous one.