12KB
CLAUDE.md
Version: 1.0.0
Purpose
This file contains Claude-specific operating rules for this repository.
The model-neutral operating system lives in:
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:
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:
SEARCH
READ
INSPECT
TRACE
VERIFY
before:
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:
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:
the project uses SQL Server
inspect:
connection strings
configuration
packages
existing database code
Instead of assuming:
the application uses Bootstrap
inspect:
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:
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:
"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:
SMALL CHANGE
↓
VERIFY
↓
NEXT CHANGE
rather than:
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:
noted
or:
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:
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:
.ai/skills/
for a relevant skill.
Examples:
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:
.ai/skills/skill-extractor/SKILL.md
and:
.ai/skills/skill-builder/SKILL.md
Before creating a new skill:
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:
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:
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:
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:
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:
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:
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:
file
class
function
service
configuration
script
skill
prompt
template
search for an existing equivalent.
The goal is to prevent:
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:
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:
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:
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:
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:
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:
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:
assumptions
decision rationale
tradeoffs
evidence
risks
verification
For example:
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:
.ai/skills/socratic-teacher/SKILL.md
Do not automatically produce giant tutorials.
Prefer:
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:
"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:
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:
.ai/skills/retrospective/SKILL.md
when appropriate.
27. Instruction Hygiene
Keep this file Claude-specific.
If this file begins accumulating:
project architecture
business rules
generic coding standards
general AI workflow rules
move them to the correct location.
Prefer:
CLAUDE.md
↓
small adapter
not:
CLAUDE.md
↓
second giant AGENTS.md
28. Completion Checklist
Before completing substantial work, confirm:
[ ] 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:
BETTER PROJECT STATE
and, when evidence justifies it:
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.