155 lines
4.1 KiB
Markdown
155 lines
4.1 KiB
Markdown
# 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
|
|
|
|
1. Why would this have worked before if it's broken?
|
|
2. What changed between working and not working?
|
|
3. Is there any NEW code in the path?
|
|
|
|
If answer to #3 is YES → investigate new code FIRST.
|
|
|
|
---
|
|
|
|
## Feature Addition Approach
|
|
|
|
1. **Understand first** - Read existing code, understand patterns
|
|
2. **Plan before coding** - Explain changes, get confirmation
|
|
3. **Minimal changes** - Don't refactor unrelated code
|
|
4. **Test incrementally** - Small steps, verify each
|
|
5. **Document** - Update TODO, CHANGELOG, relevant docs
|
|
|
|
---
|
|
|
|
## Code Change Rules
|
|
|
|
1. **Focus on explicit request** - Don't add unrequested changes
|
|
2. **Root cause analysis** - For non-trivial bugs, explain before fixing
|
|
3. **Explain fundamental changes** - Before implementing, discuss
|
|
4. **Don't over-commit** - Test before suggesting commit
|
|
5. **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
|
|
|
|
1. Unit test new functions
|
|
2. Integration test with mocked APIs
|
|
3. End-to-end test with real systems
|
|
4. Log everything during testing
|
|
5. 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
|
|
|
|
---
|
|
|
|
<!--
|
|
Add new rules below. Use next available R### number.
|
|
Subproject-specific rules go in subproject's PRINCIPLES.md
|
|
-->
|