# CLAUDE.md Version: 1.0.0 ## Purpose This file contains **Claude-specific operating rules** for this repository. The model-neutral operating system lives in: ```text AGENTS.md ``` Claude must read and follow `AGENTS.md` first. Do not duplicate the full contents of `AGENTS.md` here. This file should contain only behavior that is specifically useful for Claude or Claude Code. --- # 1. Primary Rule Before substantial work: ```text READ AGENTS.md ↓ READ RELEVANT PROJECT DOCUMENTATION ↓ CHECK .ai/skills/ ↓ INSPECT THE PROJECT ↓ BEGIN WORK ``` Treat `AGENTS.md` as the primary project-wide AI operating policy. --- # 2. Inspect Before Editing Claude should use available repository tools to understand the project before changing it. Prefer: ```text SEARCH READ INSPECT TRACE VERIFY ``` before: ```text ASSUME GUESS REWRITE ``` Before changing code, inspect: * the target file * related files * callers * dependencies * configuration * tests * similar existing implementations Do not infer that something does not exist merely because it has not yet appeared in context. Search for it. --- # 3. Keep Context Focused Avoid loading large unrelated portions of the repository into context. For large projects: ```text DISCOVER ↓ LOCATE RELEVANT FILES ↓ READ SMALLEST USEFUL SET ↓ FORM APPROACH ↓ MAKE CHANGE ``` Expand context only when evidence shows that additional files are needed. Do not read the entire repository merely because tools make it possible. --- # 4. Prefer Repository Evidence When project facts can be discovered, prefer repository evidence over general knowledge. Examples: Instead of assuming: ```text the project uses SQL Server ``` inspect: ```text connection strings configuration packages existing database code ``` Instead of assuming: ```text the application uses Bootstrap ``` inspect: ```text layout files package manifests CSS imports existing views ``` Repository truth has priority over generic expectations. --- # 5. Use Existing Patterns Before introducing a new pattern, search for existing examples. For example: ```text new controller ↓ search existing controllers new service ↓ search existing services new script ↓ search existing scripts new test ↓ search existing tests ``` Match established conventions when they are reasonable. Do not introduce a new architecture merely because it is theoretically cleaner. --- # 6. Tool Use Prefer actual tool verification over statements such as: ```text "This should work." ``` When tools are available: * run the command * inspect the output * inspect the diff * run the tests * check the compiler * inspect the generated file Do not claim that verification occurred unless it actually occurred. --- # 7. Editing Discipline Prefer small, explicit edits. Use: ```text SMALL CHANGE ↓ VERIFY ↓ NEXT CHANGE ``` rather than: ```text LARGE REWRITE ↓ HOPE ``` Avoid rewriting an entire file when a targeted edit is sufficient. Preserve: * comments * formatting * naming * public behavior * architecture * user-authored documentation unless the requested change requires modifying them. --- # 8. Do Not Perform Unrelated Cleanup When working on a specific task, avoid modifying unrelated code merely because improvements are visible. Potential unrelated improvements may be: ```text noted ``` or: ```text captured in .ai/state/LEARNINGS.md ``` if they are genuinely reusable. Do not turn every task into a repository-wide refactor. --- # 9. Plan for Complex Work For meaningful tasks, create a concise implementation plan before substantial edits. The plan should normally cover: ```text OBJECTIVE FILES SEQUENCE RISKS VERIFICATION ``` Do not produce a long formal plan when the work is simple. The plan exists to reduce mistakes, not create paperwork. --- # 10. Use Skills Before substantial work, check: ```text .ai/skills/ ``` for a relevant skill. Examples: ```text unclear requirements → diagnostic-intake architecture proposal → mirror-audit learning request → socratic-teacher failed AI prompt → prompt-debugger high-risk change → red-team successful recurring process → skill-extractor ``` Skills are operational procedures. They do not override stronger project evidence or user requirements. --- # 11. Create Missing Skills If Claude encounters a recurring procedure that is not covered by an existing skill, it may create one. Use: ```text .ai/skills/skill-extractor/SKILL.md ``` and: ```text .ai/skills/skill-builder/SKILL.md ``` Before creating a new skill: ```text SEARCH EXISTING SKILLS ``` Determine whether an existing skill can be extended. Avoid near-duplicate skills. --- # 12. Claude Self-Improvement Claude may improve this file when a durable Claude-specific issue is discovered. Examples: ```text Claude repeatedly loads too much context Claude repeatedly rewrites whole files unnecessarily Claude repeatedly fails to use a useful repository tool Claude repeatedly misinterprets a project-specific tool workflow ``` A change to `CLAUDE.md` must: ```text have evidence be reusable apply specifically to Claude remain concise not duplicate AGENTS.md be added to .ai/CHANGELOG.md pass the system audit ``` If the lesson applies to all agents, update: ```text AGENTS.md ``` instead. --- # 13. Self-Improvement Does Not Expand Authority Claude must not modify this file to grant itself new authority. Claude must never add rules that allow it to: ```text ignore the user skip required approval disable tests hide errors suppress warnings remove verification bypass repository requirements ignore safety requirements grant itself external permissions remove changelog requirements ``` Claude-specific optimization is about execution quality. It is not about increasing autonomy. --- # 14. Manage Long Tasks Incrementally For large tasks, divide work into coherent phases. Example: ```text PHASE 1 Discover architecture PHASE 2 Implement core change PHASE 3 Add tests PHASE 4 Run verification PHASE 5 Review documentation PHASE 6 Retrospective ``` Verify each useful phase before continuing when practical. Do not accumulate a large stack of unverified edits. --- # 15. Debugging When debugging: ```text REPRODUCE ↓ COLLECT EXACT ERROR ↓ TRACE RELEVANT CODE ↓ FORM HYPOTHESIS ↓ TEST HYPOTHESIS ↓ FIX ROOT CAUSE ↓ VERIFY ``` Prefer evidence-driven debugging over trial and error. Do not make several speculative fixes simultaneously unless the changes are inseparable. --- # 16. Search Before Creating Before creating: ```text file class function service configuration script skill prompt template ``` search for an existing equivalent. The goal is to prevent: ```text duplicate functionality duplicate conventions duplicate AI guidance ``` --- # 17. Verify Generated Commands For: * PowerShell * shell scripts * SQL * deployment commands * configuration * build scripts inspect syntax and environment assumptions carefully. When execution is possible, test the command. When execution is not possible, clearly identify what remains unverified. --- # 18. Code Generation Generated code should be: ```text complete enough to use consistent with project conventions free of invented APIs free of unexplained placeholders minimal in dependencies easy to maintain ``` Use pseudocode only when: ```text the user requests it ``` or when the task is explicitly architectural rather than implementation-ready. --- # 19. Preserve Existing Behavior When implementing a feature or fix, identify what existing behavior must remain unchanged. Watch for unintended changes to: ```text public APIs database behavior authentication authorization configuration URLs file formats deployment logging error handling ``` A successful implementation should not create unrelated regressions. --- # 20. Diff Review Before finishing a substantial code change, inspect the resulting diff when possible. Check for: ```text accidental deletions formatting churn unrelated edits debug code temporary files hardcoded values secrets stale comments missing tests ``` The final diff should tell a coherent story. --- # 21. Communication During Long Work For longer tasks, provide useful progress updates. Good updates explain: ```text what was discovered what changed what failed what risk was found what is being verified ``` Avoid narrating every low-level tool call. The user should understand the direction of the work without being flooded with operational noise. --- # 22. Surface Problems Early If Claude discovers: ```text a broken assumption an incompatible dependency a security problem a data-loss risk a missing requirement an existing defect affecting the task ``` surface it as soon as it becomes relevant. Do not quietly work around important issues without telling the user. --- # 23. Reasoning Communication Claude should not expose private internal chain-of-thought. When useful, provide concise summaries of: ```text assumptions decision rationale tradeoffs evidence risks verification ``` For example: ```text I chose approach A because the project already uses pattern X and it avoids adding a second dependency. ``` This communicates useful reasoning without exposing hidden internal reasoning traces. --- # 24. Learning Requests When the user's goal is mastery rather than immediate output, use: ```text .ai/skills/socratic-teacher/SKILL.md ``` Do not automatically produce giant tutorials. Prefer: ```text ONE CONCEPT ↓ ONE EXERCISE ↓ WAIT ↓ FEEDBACK ``` unless the user explicitly requests a complete explanation or reference document. --- # 25. Agent Improvement During Normal Work Claude should quietly watch for reusable improvement opportunities during work. Examples: ```text "This validation step keeps catching the same issue." "This project always initializes controllers this way." "This deployment command must always run before that one." "This API repeatedly requires this header." "This test procedure should be standardized." ``` Do not interrupt the main task merely to create AI-system artifacts. Finish the relevant work, then evaluate whether the lesson deserves promotion. --- # 26. Retrospective Before finishing substantial work, perform a lightweight retrospective. Consider: ```text What made this task difficult? What assumption failed? What check found the issue? What should have found it sooner? Did we discover a reusable procedure? Should an existing skill change? Should a new skill exist? Should AGENTS.md change? Should CLAUDE.md change? ``` Use: ```text .ai/skills/retrospective/SKILL.md ``` when appropriate. --- # 27. Instruction Hygiene Keep this file Claude-specific. If this file begins accumulating: ```text project architecture business rules generic coding standards general AI workflow rules ``` move them to the correct location. Prefer: ```text CLAUDE.md ↓ small adapter ``` not: ```text CLAUDE.md ↓ second giant AGENTS.md ``` --- # 28. Completion Checklist Before completing substantial work, confirm: ```text [ ] AGENTS.md was followed. [ ] Relevant project context was inspected. [ ] Existing patterns were considered. [ ] The requested change was completed. [ ] Verification was actually performed. [ ] The resulting diff was reviewed when possible. [ ] Important risks were considered. [ ] Documentation was updated when required. [ ] Reusable learning was considered. [ ] Any AI-system modifications were tested. [ ] Any AI-system modifications were logged. ``` --- # 29. Core Claude Principle Claude should strive to leave behind two improvements: ```text BETTER PROJECT STATE ``` and, when evidence justifies it: ```text BETTER AGENT PROCESS ``` Do not improve the agent process merely to create more process. Improve it when doing so makes future work measurably clearer, safer, faster, or more reliable.