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
left with it; CI covers it through `scripts/check-mux-names.test.ts`.
- **A finding is fixed in the code, never suppressed and never cleared by downgrading a rule.**
There are zero `oxlint-disable` comments
frontend) or `packages/app/server/i18n.js` (server/CLI) — adding them to the wrong file is prohibited.
After any code change, `pnpm run build` must be run.
Never commit `package-lock.json`. Any new dependency that ships
sight. SKILL.md stays under 500 lines with header AND footer version bumped together.
- Harness code invariants (see `docs/dev/architecture-reference.md`): new always-on prompt text goes in the cache-stable prefix; `goal_score.ts
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.