Anti-patterns

By agent-playbook · 0 stars

| Anti-pattern | Effect | Fix |
|---|---|---|
| Pasted README or architecture doc | Context spent on files the agent can open | One-line pointer |
| Full directory tree | Visible in the repo; goes stale | Non-obvious directories only |
| Restated lint/format rules | Duplicates tooling; can contradict it | "Run `pnpm lint --fix`" |
| Vague virtues ("write clean code") | Not actionable | The concrete rule |
| Commands that fail | Wasted turns, invented alternatives | Run each in a clean checkout |
| Stale versions or removed scripts | Wrong instructions followed confidently | Review when tooling changes |
| Status notes ("this sprint we migrate X") | Expire; confuse later sessions | Issues or PR descriptions |
| Secrets, tokens, credentials | Committed and sent to model providers | Env var names only |
| Pages of "IMPORTANT", "MUST" | Priorities flatten | Emphasis on at most two rules |
| "Don't use X" with no alternative | Agent guesses the alternative | "Use Y, not X" |
| Root says pnpm, package says npm, no override stated | Tool picks either | "Unlike the root, ..." |
| Narrative paragraphs | Harder to follow and prune | Bullets and tables |
| Persona lines ("You are a world-class engineer") | Tokens, little effect | Delete |
| Separate CLAUDE.md, `.cursorrules`, copilot-instructions.md | Drift | One AGENTS.md plus imports or native reads |
| "Please read AGENTS.md" in prose | May never be opened | `@AGENTS.md` or native support |
| SQL, test and CSS rules in the root file | Always-on cost | Path-scoped rules |
| Leftover `.cursorrules` (Zed) or `CLAUDE.local.md` (Claude Code) | Shadows AGENTS.md | Delete, or change the loading setting |
| Symlinked files with Windows users | One-line text files on checkout | Imports |
| Must-never rules only in the file | Not enforced | Permissions, hooks, branch protection, CI |
| Unreviewed agent rewrites of the file | Unchecked drift | Review the diff like code |