complexity, stop and reassess rather than pushing through.
- **Use available skills proactively**: `/review-work` for codereview, `/update-docs` after significant changes, `/deploy` for deployments.
- **Context7 first**: When working with external libraries
configurable (default 2). Prevents runaway spawning.
### Runtime Modes: headless vs tmux (Claude Code)
Claude Code agents can run in two modes. **Headless is the shipped default for new
projects
offline, from the artifacts alone. CLI coding agents work out of the box (Claude Code, Codex, Gemini CLI, and 52 more), and the same layer governs any agent workload
prevent the same mistake
- Ruthlessly iterate on these lessons until the mistake rate drops
- Review lessons at session start for a project
### 3. Verification Before Done
- Never mark a task
style and typing before review.
- `bun run test` runs the Vitest suite once; combine with `bun run prepublishOnly` before publishing to exercise the full pipeline.
## Coding Style & Naming Conventions
- Follow
position marker
- Position calculation accounts for injected `SET statement_timeout` prefix
- Returns structured errors: `{ code, message, formattedError, position, detail, hint }`
### Type Generation
Type generation (`npm run gen:types:*`) works
analyze dependencies before parallel execution, report progress per unit.
- **Rule 3 — Post-Implementation Review**: After coding, provide potential-issue list (edge cases, error/concurrency scenarios), suggested test cases, known limitations/assumptions, additional
file per run**. Multi-file outputs (staging files, per-worker dumps, split reports) make review impossible.
- **Default: work in a single file.** If the task fits in one file, never
files, and check related code for consistency. Never create docs (*.md, README) unless asked.
- Prefer `rg` over `grep`.
- Use the `writing-guidelines` skill to review documentation or interface copy
lint/type suppression comments. Use
static production imports and fix violations at their source. See
[code quality](docs/bad-smell.md) for the project's specific boundaries.
- Write repository artifacts, comments, commits, issues
command for complete legacy code workflow, assessment guidance, and commit sequence examples.
### Post-Implementation CodeReview and Refactoring
**After all tests pass, always consider refactoring opportunities in new code
Think of yourself as a careful craftsperson who measures twice and cuts once.
When reviewingcode, always state: "I've read through [specific sections] and understand [key functionality]" before making
A file Claude Code reads at the start of every session. It holds the commands, conventions and warnings the agent needs for this project.
Where does it go?
At the repository root. Claude Code also reads CLAUDE.md files in subdirectories when it works there.
What should it contain?
Build and test commands, the project's layout, conventions that aren't obvious from the code, and mistakes to avoid. Short files tend to work better than long ones.
CLAUDE.md or AGENTS.md?
Claude Code reads CLAUDE.md; most other agents read AGENTS.md. Many projects keep one and point the other at it.