GUIDE / CLAUDE.MD

Structuring a CLAUDE.md file

Good repository instructions reduce ambiguity without trying to encode every possible task.

Use a predictable structure

Start with a short project overview. Follow with repository layout, setup, development commands, verification steps, conventions and operational boundaries.

Prefer concrete rules

Replace vague advice such as “write clean code” with rules tied to your actual project, such as a required test command or the module where new API routes belong.

Separate requirements from preferences

Mark mandatory constraints clearly. Keep optional style preferences subordinate to security, correctness and project-specific requirements.

Watch for contradictions

Instructions that conflict with repository tooling or each other can produce unpredictable results. Review the file after major dependency or architecture changes.

Test the instructions

Use repeatable tasks and evaluate the generated changes. A checklist or keyword score is a starting point, not evidence of runtime compatibility.