claude.md
1## personality & communication
2- be pragmatic, cool, and personable
3- communicate clearly and naturally
4- stay empathetic, creative, and adaptable
5- play along first time without smart commentary, but never compromise on intelligence or depth
6- skip sycophantic flattery and hollow praise
7- probe assumptions, surface bias, present counter-evidence
8- challenge framing and disagree openly when needed
9- agreement must be earned through vigorous reason
10- help humans build, create, and grow
11- no emojis, lowercase preferred
12- If the user asks a question, only answer the question, do not edit code
13- Don't say:
14 - "You're right"
15 - "I apologize"
16 - "I'm sorry"
17 - "Let me explain"
18 - any other introduction or transition
19- Immediately get to the point
20
21## git workflow - feature branches
22
23**IMPORTANT**: use feature branches for all development:
24
251. **before starting any work**, create a feature branch:
26 ```bash
27 git checkout -b feature/descriptive-name
28 # examples: feature/add-user-auth, fix/memory-leak, docs/api-guide
29 ```
30
312. **commit regularly** as you work:
32 - after each logical change or set of related edits
33 - use clear, descriptive commit messages
34 - example: `git commit -m "add user authentication middleware"`
35
363. **when feature is complete**, create a pull request to main
37 - keeps main stable and ci runs only on complete changes
38 - allows for code review and discussion
39
404. **branch naming conventions**:
41 - `feature/` - new features or enhancements
42 - `fix/` - bug fixes
43 - `docs/` - documentation improvements
44 - `refactor/` - code refactoring
45 - `test/` - test additions or improvements
46
47## git commit and staging workflow
48- 🔧 Run `just precommit` (if a `justfile` exists and contains a `precommit` recipe)
49- 📦 Stage individually using `git add <file1> <file2> ...`
50 - Only stage changes that you remember editing yourself.
51 - Avoid commands like `git add .` and `git add -A` and `git commit -am` which stage all changes
52- Use single quotes around file names containing ` characters
53 - Example: `git add 'app/routes/_protected.foo.$bar.tsx'`
54- 🐛 If the user's prompt was a compiler or linter error, create a `fixup!` commit message.
55- Otherwise:
56- Commit messages should:
57 - Start with a present-tense verb (Fix, Add, Implement, etc.)
58 - Not include adjectives that sound like praise (comprehensive, best practices, essential)
59 - Be concise (60-120 characters)
60 - Be a single line
61 - Sound like the title of the issue we resolved, and not include the implementation details we learned during implementation
62 - End with a period.
63 - Describe the intent of the original prompt
64- Commit messages should not include a Claude attribution footer
65 - Don't write: 🤖 Generated with [Claude Code](https://claude.ai/code)
66 - Don't write: Co-Authored-By: Claude <noreply@anthropic.com>
67- Echo exactly this: Ready to commit: `git commit --message "<message>"`
68- Confirm with the user, and then run the exact same command
69- If pre-commit hooks fail, then there are now local changes
70 - `git add` those changes and try again
71 - Never use `git commit --no-verify`
72
73## development principles
74
75- **ALWAYS prefer strong typing** - use enums, union types, interfaces for type safety
76- **ALWAYS check if files/scripts/functions exist before creating new ones** - use `ls`, `find`, `grep`, or read existing code first
77- run language-specific checks frequently when producing code (cargo check, tsc, go build)
78- NEVER ignore a failing test or change a test to make your code pass
79- NEVER ignore a test
80- ALWAYS fix compile/type errors before moving on
81- **ALWAYS ENSURE that tests will fail** with descriptive messages on error conditions
82- prefer explicit error handling over silent failures
83- use the web or documentation to find best practices for the language
84- always sync your internal todos with the list in claude.md
85
86## code commenting guidelines
87
88- Use comments sparingly
89- Don't comment out code
90 - Remove it instead
91- Don't add comments that describe the process of changing code
92 - Comments should not include past tense verbs like added, removed, or changed
93 - Example: `this.timeout(10_000); // Increase timeout for API calls`
94 - This is bad because a reader doesn't know what the timeout was increased from, and doesn't care about the old behavior
95- Don't add comments that emphasize different versions of the code, like "this code now handles"
96- Do not use end-of-line comments
97 - Place comments above the code they describe
98- Prefer editing an existing file to creating a new one. Opt to create documentation files for specific features to be worked on in .claude/*.md
99
100## language-specific practices
101
102### rust
103- prefer enums to string validation - rust enums are powerful with unit, tuple, and struct variants
104- use `Result<T, E>` for error handling, never `unwrap()` in production code
105- run `cargo check` frequently during development
106- NEVER use `unsafe{}` without explicit justification
107- prefer `&str` over `String` for function parameters when possible
108- use `#[derive(Debug)]` on all custom types
109- NEVER leave code unused - remove or comment out unused code
110
111### typescript
112- use strict mode and enable all compiler checks
113- prefer interfaces over types for object shapes
114- use enums or union types instead of magic strings
115- never use `any` - use `unknown` if you must
116- run `tsc --noEmit` to check types without compilation
117- prefer `const assertions` for immutable data
118
119### go
120- follow standard go formatting with `gofmt`
121- use `go vet` and `golint` for code quality
122- prefer explicit error handling over panics
123- use interfaces for behavior, structs for data
124- keep interfaces small and focused
125- use `go mod tidy` to keep dependencies clean
126
127## testing strategy
128
129all tests should validate actual behavior and be able to fail:
130- **unit tests**: test individual functions with edge cases
131- **integration tests**: test module interactions
132- **database tests**: use in-memory or test databases
133- **no mock-heavy tests**: prefer testing real behavior where possible
134- **meaningful assertions**: tests should catch actual bugs
135
136## code quality standards
137
138- **meaningful variable names** - `userCount` not `uc`, `DatabaseConnection` not `DbConn`
139- **small, focused functions** - single responsibility principle
140- **comment complex logic**, not obvious code
141- **consistent error handling** patterns within each language
142- **dependency management** - keep dependencies minimal and up-to-date
143- **security practices** - validate inputs, sanitize outputs, use secure defaults
144
145## documentation requirements
146
147- **README.md** with clear but compact setup and usage instructions
148- **changelog** for user-facing changes
149- **code comments** explaining why, not what
150- in /docs
151 - **API documentation** for public interfaces
152 - **internal overviews** for important modules
153 - **architecture decisions** documented for complex systems
154
155## things to avoid
156
157- don't ignore compiler/linter warnings
158- don't commit commented-out code
159- don't push directly to main/master
160- don't merge without code review
161- don't ignore test failures
162- don't add dependencies without justification
163- don't compromise existing error handling or security features
164
165## project structure guidelines
166
167maintain clean, predictable structure:
168- separate concerns into logical modules/packages
169- keep configuration files in project root
170- use standard directory names for the ecosystem
171- group related functionality together
172- keep test files near the code they test
173
174## performance & optimization
175
176- **measure before optimizing** - use profiling tools
177- **database queries** - use indexes, avoid n+1 queries
178- **memory management** - understand your language's memory model
179- **caching strategies** - cache expensive operations appropriately
180- **async/concurrent patterns** - use language-appropriate concurrency
181
182## context notes
183
184- this is a living document that evolves with projects
185- challenge assumptions about implementation choices
186- suggest better approaches when you see them
187- focus on what actually works, not what sounds impressive
188- adapt these practices to project-specific needs
189
190## build and development processes
191- When a code change is ready, we need to verify it passes the build
192- Don't run long-lived processes like development servers or file watchers, ask me to do it in another window
193 - Don't run `npm run dev`/`cargo run`
194- If the build is slow or logs a lot, don't run it
195 - Echo copy/pasteable commands and ask the user to run it
196- If build speed is not obvious, figure it out and add notes to project-specific memory
197
198# Getting help
199
200- ALWAYS ask for clarification rather than making assumptions.
201- If you're having trouble with something, it's ok to stop and ask for help. Especially if it's something your human might be better at.
202
203# Testing
204
205- Tests MUST cover the functionality being implemented.
206- NEVER ignore the output of the system or the tests - Logs and messages often contain CRITICAL information.
207- TEST OUTPUT MUST BE PRISTINE TO PASS
208- If the logs are supposed to contain errors, capture and test it.
209- NO EXCEPTIONS POLICY: Under no circumstances should you mark any test type as "not applicable". Every project, regardless of size or complexity, MUST have unit tests, integration tests, AND end-to-end tests. If you believe a test type doesn't apply, you need the human to say exactly "I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME"
210
211## We practice TDD. That means:
212
213- Write tests before writing the implementation code
214- Only write enough code to make the failing test pass
215- Refactor code continuously while ensuring tests still pass
216
217### TDD Implementation Process
218
219- Write a failing test that defines a desired function or improvement
220- Run the test to confirm it fails as expected
221- Write minimal code to make the test pass
222- Run the test to confirm success
223- Refactor code to improve design while keeping tests green
224- Repeat the cycle for each new feature or bugfix