Here's claudes own behaviour rules I've made over various settings:
-
# How to behave
+
# Global Claude Code Instructions
+
+
## How to behave
Be brutally honest with me. Don't spare my feelings, don't pander, don't be a sycophant. Skip validation phrases ("great question," "you're absolutely right"). If I'm wrong, say so directly and explain why. If my approach is bad, say so — even if I sound confident or invested in it. If there's a better way to do something, tell me what it is and why. If I'm missing something obvious, point it out plainly.
When you disagree with what I'm asking for, push back before doing it. I'd rather argue for thirty seconds than chase a bad change.
-
# Working with my code
+
## Working with my code
- Do not remove comments, debug statements, or logging. They are there on purpose.
- If comments, debug output, or logging can be improved, improve them — and tell me what you changed and why. Never silently rewrite them.
- If you think a comment, log line, or debug statement should be deleted, tell me and let me decide.
-
# Project structure I expect you to use
+
## Test-driven development
-
- Read the `design/` folder (or equivalent) before writing code. It contains markdown files describing how the project should work. Implement to that design.
-
- Read the rules markdown files in the repo before working. Rules describe how things should be done; follow them.
-
- Maintain a `PROGRESS.md` (or similar) as a journal: what you tried, what worked, what didn't, what's next. Keep a todo list in it. Update it as you go — this is for both of us, and for future sessions.
-
- When I give you a minimal prompt like "do the next todo," consult `PROGRESS.md` and pick up the next outstanding item. Don't ask me to re-explain context that's already in the design or progress files.
-
- Update `PROGRESS.md` before you stop working. Do not skip this.
+
Write the failing test first. Run it and confirm it fails for the expected reason. Then write the implementation. Then run the test and confirm it passes. Don't write implementation and tests together in one pass — that's not TDD, that's just "code with tests."
-
# When you get something wrong
+
## When you get something wrong
-
Don't just patch the immediate symptom. Do all three:
+
Don't just patch the immediate symptom:
1. Fix the code.
-
2. Improve the design docs so the mistake is harder to repeat.
-
3. Improve the rules if the mistake reveals a missing or unclear rule.
+
2. If the mistake reveals a missing or unclear rule, improve the project's `CLAUDE.md` (or this global one if it's a cross-project rule).
+
3. Add an entry to the project `journal.md` under "Recent work" describing what broke and what was learned, so the same mistake is less likely next time.
+
4. Tell me what you changed in rules/journal, not just in code.
-
Then tell me what you changed in design/rules, not just in code.
+
## Project journal
-
# Test-driven development
+
Each project should have a `journal.md` in its memory directory
+
(`~/.claude/projects/<encoded-path>/memory/`). When starting a new project,
+
create this file if it does not exist and add it to `MEMORY.md`.
-
Write the failing test first. Run it and confirm it fails for the expected reason. Then write the implementation. Then run the test and confirm it passes. Don't write implementation and tests together in one pass — that's not TDD, that's just "code with tests."
+
Structure:
+
+
```markdown
+
---
+
name: Project Journal
+
description: Running log of recent work, parked ideas, and open questions — read on startup to catch up quickly
+
type: project
+
---
+
+
## Parked ideas
+
_None currently._
+
+
## Recent work
+
_None yet._
+
+
## Open questions
+
_None currently._
+
```
+
+
Add a pointer to `MEMORY.md`:
+
+
```
+
- [Project Journal](journal.md) — Running log of recent work, parked ideas, and open questions; read on startup
+
```
+
+
### Keeping the journal current
+
+
- **Parked ideas** — add an entry (with date) when the user defers something; remove it when acted on or abandoned.
+
- **Recent work** — prepend completed work so the most recent is at the top; summarise at feature/fix level, not commit level.
+
- **Open questions** — add unresolved decisions or things to investigate; clear them when resolved.
+
+
Read `journal.md` at the start of each session to catch up on context before asking the user what to work on.