Add a "Decisions" Section to CLAUDE.md to Prevent Repeated Debates
Claude approaches every session without memory of previous conversations. If you spent 20 minutes debating whether to use REST or GraphQL and chose REST, Claude will happily re-open that debate next time if you don't record the decision.
A ## Decisions section in your CLAUDE.md closes that loop permanently.
## Decisions
### Architecture
- REST over GraphQL — we don't have complex nested query requirements
- Postgres only — no Redis caching layer until we have real performance data
- No ORM abstractions beyond what Laravel provides — direct Eloquent only
### Frontend
- Vue 3 Composition API — no Options API in new components
- Tailwind for styling — no custom CSS except for animations
- No jQuery — vanilla JS or Vue reactivity only
### Testing
- Pest for PHP tests — PHPUnit syntax only where Pest doesn't support it
- No snapshot testing — it creates noise in diffs without catching real regressions
When Claude sees this section, it stops proposing alternatives you've already rejected. It also stops asking clarifying questions about choices that are already settled.
You can be direct when writing decisions in:
## Decisions
- We are NOT switching to microservices. Do not suggest it.
- Authentication uses Sanctum, not Passport. Do not propose changing this.
- We use uuid() for primary keys. Do not use auto-incrementing integers.
Update this section whenever a meaningful debate gets resolved — it becomes a living record of your project's technical philosophy.
Every decision you document is a debate you never have to have again.
Log in to leave a comment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.