Anti-patterns
Practices that look right and fail. Reject every one, including in your own output.
1. Monolithic prompt bloat
Symptom. A CLAUDE.md that runs thousands of words, including roadmap, personas, brand voice.
Fix. One kind of content per file. Reference long docs on demand. Keep the Project-layer file under 200 lines.
2. Vague principles without examples
Symptom. "Use good judgment", "write clean code", "follow our style guide".
Fix. Behaviourally anchored rules name the exact technology, command, or pattern.
| Category | Anchored | Vague |
|---|---|---|
| Error handling | Wrap external calls in try/catch; log via Logger; never swallow exceptions. | "Write robust error handling." |
| Styling | Tailwind utilities only; conditional classes via cn(). | "Use clean styling patterns." |
| Testing | Vitest; assert on user actions; run npm run test:coverage before staging. | "Maintain high test coverage." |
| Git | Conventional Commits; one-file scope where reasonable. | "Commit often with helpful messages." |
3. Placeholder comments
Symptom. // TODO: implement this, pass # come back later in shipped code.
Fix. Every function is either fully implemented or not included. If the agent lacks context, it stops and asks.
4. Implicit local assumptions
Symptom. "Use the local Postgres" or "open the file in VS Code".
Fix. State the assumption in the Session layer, or have the agent ask. Never bake personal environment into the Project layer.
5. Over-exposing tools
Symptom. MCP config exposes every tool "just in case".
Fix. Route tools by intent. See MCP principles.
6. Rules that fire everywhere
Symptom. A global rules file with both frontend and backend conventions.
Fix. Scope to file patterns. → scope
7. Stale context
Symptom. CLAUDE.md still says "we use Yarn 1" three months after migrating to pnpm.
Fix. Pre-commit hook that validates context against detected stack. → verify
8. Treating memory as repo context
Symptom. "Magnus prefers terse responses" in CLAUDE.md.
Fix. User preferences belong in agent memory or per-user config. The Project layer describes the project, not the people.
9. Negative-space silence
Symptom. No record of approaches considered and rejected.
Fix. ADRs with a "Considered alternatives" section, or docs/decisions/negative-space.md. → adr
10. Verification as an afterthought
Symptom. Context files tell the agent what to do, not how to check the result.
Fix. Every instruction that produces an artifact names the command that verifies it. → verify