4.1 KiB
Principles & Rules (Root)
Base methodology and rules for all subprojects. Subprojects can extend/override.
Core Philosophy
Small, Smart, Strong
- Small changes, well-tested
- Smart solutions, not over-engineered
- Strong foundations before features
Debugging Methodology
Inverted Confidence Rule
Code I wrote this session: 20% confidence it's correct
- Assume I made a mistake
- Prove it works before moving on
- Test thoroughly
Existing code: 80% confidence it's correct
- Assume it works as intended
- Prove it's broken before touching it
- Respect that it was tested/debugged
Debugging Decision Tree
Bug appears
├─ Is there NEW code involved?
│ └─ YES (95% probability) → Start here
│ └─ Test new code in isolation
│ └─ Compare with working baseline
│ └─ Only if proven correct → investigate old code
│
└─ Is it ONLY old code?
└─ Verify nothing changed
└─ Check environment, dependencies, inputs
Before Blaming Existing Code
- Why would this have worked before if it's broken?
- What changed between working and not working?
- Is there any NEW code in the path?
If answer to #3 is YES → investigate new code FIRST.
Feature Addition Approach
- Understand first - Read existing code, understand patterns
- Plan before coding - Explain changes, get confirmation
- Minimal changes - Don't refactor unrelated code
- Test incrementally - Small steps, verify each
- Document - Update TODO, CHANGELOG, relevant docs
Code Change Rules
- Focus on explicit request - Don't add unrequested changes
- Root cause analysis - For non-trivial bugs, explain before fixing
- Explain fundamental changes - Before implementing, discuss
- Don't over-commit - Test before suggesting commit
- Stay doubtful - Don't assume it works, verify
Error Handling
- Technical issues → Inform user, explain what's being checked
- Unexpected inputs → Handle gracefully or escalate
- Escalate early if uncertain
Testing Approach
- Unit test new functions
- Integration test with mocked APIs
- End-to-end test with real systems
- Log everything during testing
- Verify before marking task complete
Rules (Dos & Don'ts)
Hard rules for Claude behavior. Added by user based on observed issues.
Never remove rules. Only add.
Format: R###: Rule description + Context
General Behavior
R001: Do not add "co-author" or Claude Code references in commit messages Context: User preference, keep commits clean
R002: Do not say "you're absolutely right" or similar excessive validation Context: Maintain objectivity, don't sugar coat
R003: Do not assume task is done and suggest commit without testing Context: Stay doubtful, verify before declaring success
R004: Do not start implementation without confirmation when user explains feature Context: User wants to see proposed changes first, then approve
R005: When explaining changes, wait for confirmation before coding Context: Avoid wasted work on wrong approach
R006: Always show major file content for review before writing Context: User is system designer, needs to approve before files are created
R007: Commit after completing each small, logical change Context: Git history becomes a book telling the story of how the app was built. Each commit is a chapter. Keeps history clean and reviewable.
Code & Architecture
R010: Do not create new files unless absolutely necessary Context: Prefer editing existing files
R011: Do not refactor unrelated code when fixing a bug Context: Focus on explicit request only
R012: Do not introduce security vulnerabilities (injection, XSS, etc.) Context: Standard security practice
Documentation
R020: Update project docs (TODO, CHANGELOG, STATUS) after changes Context: Maintain context for future sessions
R021: Log debugging experiences in LESSONS.md Context: Don't repeat past debugging efforts