Claude Code / Codex
Instruction Prompts & Template Collection

Read the instruction file you (this agent) load (CLAUDE.md / AGENTS.md, etc.),
point out the weak spots that AI agents tend to ignore, and then rewrite it
into an effective form.

Things to look at:
- Turn vague wording into imperatives (always do X / never do Y)
- Add a "definition of done" and verification steps (running lint / test)
- Make prohibitions concrete down to the target (directory names, command names)
- If it is too long, cut it down to just the core you want enforced

First list the weak spots as bullet points, then output the full rewritten
version and apply it to that instruction file.

After identifying this repository's actual build / test / lint commands,
add a "Definition of Done" section to the instruction file you load
(CLAUDE.md / AGENTS.md, etc.).

Requirements:
- Make it a checklist in the form "do not report done until all of the following are met"
- State the real lint and test commands explicitly
- Include: leave no TODOs or debug logs in changed files, and re-read your own diff

Do not break the existing content; only add the section.

Automatically detect this repository's language and framework, and add the
corresponding best-practice rules to the instruction file you load
(CLAUDE.md / AGENTS.md, etc.).

Examples:
- Next.js: Server/Client boundary (default is Server, keep use client minimal)
- Laravel: validation via Form Requests, migration conventions
- Python: type annotations, never overwrite or fabricate raw data

Add a one-line note on the basis for your detection (which files you judged from)
before appending. Do not duplicate anything already written.

Add the following "absolute rules" to the instruction file you load
(CLAUDE.md / AGENTS.md, etc.), tailored to this repository's setup.

- Never commit secrets, .env, or credentials
- Never push / force-push unless told to
- Validate input at the boundary / never loosen authentication or authorization on your own
- Never run destructive commands (DROP / TRUNCATE / migrate:fresh, etc.) on the production DB
- Whenever you change behavior, always add or update tests

If similar rules already exist, do not duplicate them; only fill in what is missing.

Convert the contents of this `CLAUDE.md` into the `AGENTS.md` format for
OpenAI Codex and write it out.

- Keep the meaning, but reshape it into a structure that is easy for Codex
  to read (headings, bullet points)
- Keep the commands, absolute rules, and definition of done as-is
- Output it as `AGENTS.md` at the root

Convert the contents of this `CLAUDE.md` into Cursor's Project Rules format
(`.mdc` files under `.cursor/rules/`).

- Split the rules into meaningful units
- Separate the rules that should always apply from the rules that apply
  only to specific file types
- Set the appropriate apply conditions (globs, etc.) at the top of each file

Inspect this monorepo's structure and create the instruction files you
(this agent) load (Claude Code uses CLAUDE.md, Codex uses AGENTS.md, etc.),
split as follows.

- At the root: rules common to the whole repo
  (commit conventions, secret protection, the overall definition of done)
- In each package/app directory: only the rules and commands specific to that stack

Avoid duplication, and add a one-line note in each package saying "follow the
common rules at the root." At the end, report a list of what you placed in which directory.

# Project: <name>

## What this is
A one-paragraph overview of the app. What it does, who uses it, and the tech
stack (language, framework, DB, runtime).

## Commands
- Dev server: `npm run dev`
- Build:      `npm run build`
- Test:       `npm test`
- Lint:       `npm run lint`

## Conventions
- Language is TypeScript (strict). Do not use `any`.
- Match the style of the file you are currently editing. Always pass Lint before finishing.
- Keep changes minimal; do not touch unrelated lines (no unrelated reformatting).

## Absolute rules (strictly enforced)
- Before reporting done, always run the tests and Lint above and make them pass.
- Never, ever commit secrets, .env, or build artifacts.
- Prefer editing existing files over creating new ones.
- When requirements are vague, ask exactly one clarifying question before making a large change.

## Off-limits (unless told otherwise)
- CI config, dependency versions, infrastructure setup.

# <name>

- Stack: <e.g. Next.js + TypeScript + PostgreSQL>
- Always run before finishing: `npm run lint` and `npm test` (both must pass)
- Match the existing style. Do not reformat unrelated lines.
- Do not commit secrets or .env. Do not push until told to.
- When vague, do not guess; ask exactly one question.

# Next.js (App Router) + TypeScript

## Stack
Next.js (App Router), TypeScript strict, Tailwind CSS, <your-ORM>

## Commands
- Dev:   `npm run dev`
- Build: `npm run build`   # must pass with no type errors
- Lint:  `npm run lint`
- Test:  `npm test`

## Architecture rules
- Default to Server Components. Add "use client" only when state, effects, or
  browser APIs are needed. Keep Client Components small and at the leaves.
- Fetch data in Server Components or Route Handlers.
  Do not fetch initial data in useEffect.
- Co-locate components with their route segment. Shared UI goes in `components/`.
- Always schema-validate external input at the boundary (e.g. Zod).

## Conventions
- No `any`. Give public functions explicit return types.
- Use the existing design tokens / Tailwind classes. Do not add colors on your own.
- Keep `page.tsx` thin; push logic into functions and components.

## Definition of done
`npm run build`, `npm run lint`, and `npm test` all pass with exit code 0.
No `any`, no unused exports, no leftover console.log.

# React (Vite) + TypeScript

## Commands
- Dev:   `npm run dev`
- Build: `npm run build`
- Lint:  `npm run lint`
- Test:  `npm test` (Vitest + Testing Library)

## Rules
- Function components and Hooks only. Do not use class components.
- Keep state to the minimum, in the order "local -> Context -> state library."
  Do not lift state up to global needlessly.
- Confine side effects to useEffect, and write the dependency array correctly.
- Separate UI from logic. Group data fetching into dedicated hooks (useXxx).
- Accessibility: give interactive elements appropriate roles and keyboard operation.

## Conventions
- No `any`. Define props with types.
- Match the style of the existing components and styles.

## Definition of done
`npm run build`, `npm run lint`, and `npm test` pass with exit code 0.

# Node.js API (Express / Hono) + TypeScript

## Commands
- Dev:   `npm run dev`
- Build: `npm run build`
- Test:  `npm test`
- Lint:  `npm run lint`

## Rules
- Schema-validate all input (body, query, params, headers) at the boundary.
- Do not swallow errors. Return them typed through a central error handler.
- Read secrets from environment variables. Do not hardcode them in code.
- Layer DB access (route -> service -> repository).
- Return a consistent JSON shape (unify the success and failure shapes).

## Absolute rules
- Do not skip or loosen authentication / authorization logic on your own.
- Always verify authorization when adding a publicly exposed endpoint.
- Do not log personal information, tokens, or passwords.

## Definition of done
`npm test` (happy path + error cases) and `npm run lint` pass.

# Laravel + PHP

## Commands
- Serve:   `php artisan serve`
- Migrate: `php artisan migrate`
- Test:    `php artisan test`
- Format:  `./vendor/bin/pint`   # run before finishing

## Conventions (follow the Laravel way)
- Use Eloquent relations. Avoid raw SQL without a clear reason.
- Validate input in Form Request classes. Do not do it inside controllers.
- Keep controllers thin. Push business logic into Services / Actions.
- Every schema change gets a new migration. Do not edit ones already run.
- Use named routes and route model binding.

## Absolute rules
- Never, ever commit `.env` or real credentials.
- Do not run destructive commands like `migrate:fresh` against the production DB.
- Whenever you change behavior, always add or update tests (`php artisan test`).

## Definition of done
Both `php artisan test` and `./vendor/bin/pint --test` pass.

# Python / data analysis

## Environment
- Use the project venv `.venv`. Do not install globally.
- Install: `pip install -r requirements.txt`
- Run: `python -m src.main`
- Test: `pytest`
- Format: `ruff check .` and `ruff format .`

## Conventions
- Add type annotations to every function signature. Run `mypy src` if configured.
- Do not put logic in notebooks. Reusable code goes in `src/`.
- Fix the seed for anything using randomness, so results are reproducible.

## Absolute data rules (most important)
- Do not silently fill in or fabricate missing values. If there are missing
  values, report them and confirm how to handle them.
- Do not overwrite raw data files. Write output to `data/processed/`.
- Document all assumptions (filters, excluded rows, units) in code comments.

## Definition of done
`pytest` passes, `ruff check .` is clean, and the results reproduce from a clean state.

# Go

## Commands
- Build:  `go build ./...`
- Test:   `go test ./...`
- Format: `gofmt -w .` and `go vet ./...`

## Conventions
- Do not swallow errors. Always handle them with `if err != nil`, and return
  them with context (`fmt.Errorf("...: %w", err)`).
- Keep nesting shallow with early returns.
- Use concurrency only when needed. Watch for goroutine leaks and races
  (make `go test -race` pass).
- Comment exported symbols. Prefer the standard library.

## Absolute rules
- Do not add unnecessary abstractions or interfaces (create them when needed).
- Before adding a dependency, first check whether the standard library suffices.

## Definition of done
`go build ./...`, `go vet ./...`, and `go test -race ./...` all pass.

# Rust

## Commands
- Build:  `cargo build`
- Test:   `cargo test`
- Lint:   `cargo clippy -- -D warnings`
- Format: `cargo fmt`

## Conventions
- Do not casually use `unwrap()` / `expect()` in production code.
  Handle `Result` / `Option` correctly with `?` or match.
- `unsafe` is banned in principle. If truly necessary, state the reason in a comment.
- Follow the compiler on borrowing and lifetimes. Rethink the design before
  escaping with `clone()`.
- Make error types meaningful with `thiserror` / `anyhow`, etc.

## Definition of done
`cargo build` and `cargo test` pass, and
`cargo clippy -- -D warnings` reports zero warnings.

# Ruby on Rails

## Commands
- Serve:   `bin/rails server`
- Migrate: `bin/rails db:migrate`
- Test:    `bin/rails test` (or `bundle exec rspec`)
- Format:  `bundle exec rubocop -A`

## Conventions (follow the Rails way)
- Respect "convention over configuration"; do not invent your own structure.
- Avoid fat controllers / models. Push logic into Services / Concerns.
- Restrict input with strong parameters.
- Avoid N+1 (use `includes`).
- Schema changes get a new migration. Do not edit ones already run.

## Absolute rules
- Never, ever commit `.env` or credentials.
- Do not run destructive commands against the production DB.
- When you change behavior, add or update tests.

## Definition of done
Tests and `bundle exec rubocop` pass.

# SQL / database migrations

## Absolute rules (data protection comes first)
- Do not run destructive operations against production data on your own
  (DROP / TRUNCATE / unconditional DELETE or UPDATE).
- Migrations must provide a rollback procedure, not just the forward direction.
- Do not edit migrations already run. Always add new ones.
- Drop or rename columns in stages ("add -> migrate -> retire"); do not do it in one shot.

## Query conventions
- Avoid `SELECT *`; specify the columns you need.
- Confirm that WHERE / JOIN conditions can use an index.
- Split large updates into batches to keep lock time short.
- For destructive verification queries, first confirm the affected count with a `SELECT` before running.

## Definition of done
Both apply and rollback succeed in a staging-equivalent environment, and you
have confirmed no unintended changes to existing data.

# Test-driven approach

When changing behavior, follow this loop every time:
1. Write a "failing test" that expresses the desired behavior first.
2. Run the test and confirm it fails for the right reason.
3. Write the minimum code needed to make the test pass.
4. Run the full test suite and confirm everything is green.
5. Refactor while keeping it green.

## Absolute rules
- Do not delete or skip tests to make the suite pass.
- Do not weaken assertions to make things green.
- If a test really is wrong, explain why before changing it.
- New code without tests is not "done."

## Definition of done
The full suite passes, coverage has not dropped, and reverting the
implementation makes the new test fail (i.e. it is a meaningful test).

# Debugging approach

Proceed in this order. Do not fix by guessing:
1. Establish the reproduction steps (how to trigger the bug).
2. Write out the expected behavior and the actual behavior, one sentence each.
3. Form a hypothesis. Verify it with logs or a minimal repro before fixing.
4. Once you have identified the cause, apply the minimal fix.
5. After fixing, confirm the bug is gone via the repro steps and that existing tests pass.
6. If possible, add a regression test that catches this bug.

## Absolute rules
- Do not change multiple places at once while the cause is unknown.
- Do not stop at "it works for now." Explain why it was fixed.
- Do not mix unrelated refactoring into debugging.

# Refactoring approach

## Core principle
Do not change externally observable behavior. Do not change outputs or side
effects for any input at all.

## Steps
1. Confirm first that tests exist for the target area and are green.
   If not, write characterization tests that pin down the current behavior first.
2. Change in small, single steps, running the tests after each step.
3. Keep one commit = one kind of improvement.

## Absolute rules
- Do not mix feature additions or bug fixes into refactoring (make them separate work).
- If a test turns red, stop right there. Do not proceed.
- Do not change public API signatures on your own (confirm first if needed).

## Definition of done
All tests stay green, and the code is more readable with less duplication.

# How to write a design document

Before implementing, first write out the following in prose (do not write code):

## 1. Goal
The problem to solve, and the conditions for calling it achieved (success criteria).

## 2. Current state and constraints
The existing setup, dependencies, and constraints to respect (performance, compatibility, deadline).

## 3. Design proposal
- The chosen approach, and the approaches you considered and rejected (and why).
- The data flow, the key interfaces, and the files to change.

## 4. Risks and open questions
What could break, the assumptions that need confirming, and the points needing a decision.

## 5. Plan
Break the implementation into small steps, ordered into verifiable units.

## Rules
- Do not start implementing until this design is approved.
- List unknowns under "open questions"; do not fill them with your own assumptions.

# How to make large changes

## Core principle
Avoid one giant change. Split it so each step is independently reviewable,
testable, and (ideally) deployable.

## Steps
1. Decompose the changes leading to the final form into a sequence of small,
   independent steps, and present it.
2. For each step, write "what / why / scope of impact" in 1-2 lines.
3. After each step, run the full test suite and confirm green before moving on.
4. Proceed while preserving backward compatibility (add -> migrate -> retire the old path).

## Absolute rules
- Do not rewrite a wide area at once and "test it all together later."
- If a step grows too large, split it further.
- Keep each step at a granularity that can be reverted.

## Definition of done
Tests are green after all steps complete, and every intermediate commit is also not broken.

# Code review instructions

Review the changes, group them by severity, and report in this order:
1. CRITICAL - security holes, data loss, crashes, broken authentication
2. HIGH     - logic bugs, race conditions, missing error handling
3. MEDIUM   - performance issues, missing tests, confusing names
4. LOW      - minor style nitpicks (only if there are no higher issues)

## How to report
- For each finding: file:line / what is wrong / why it matters / a concrete fix.
- Quote only the smallest relevant snippet. Do not paste the whole file.
- If a change is correct, say so explicitly. Do not fabricate problems.

## Things not to do
- Do not bury real bugs under a pile of LOW nitpicks.
- Do not rewrite whole files. Propose the smallest diff.
- Unless there is real harm, do not flag lines outside the diff's scope.

## Output
End with a one-line verdict: APPROVE / REQUEST CHANGES / BLOCK, with a reason.

# Git / PR rules

## Commits
- Use Conventional Commits: `type(scope): summary`
  type: feat, fix, refactor, test, docs, chore.
- One commit = one logical change. Keep it small and reviewable.
- In the body, write the "why" rather than the "what."

## Absolute rules
- Do not `git push` unless told to.
- Do not force-push, rebase, or amend on shared branches / main.
- Do not commit secrets, .env, credentials, or large binaries.
- Add files by name. Do not sweep everything in with `git add -A`.

## Pull requests
- Title within 70 characters. Body is "Summary" + "Test plan (checklist)."
- Note any breaking changes.
- Do not merge. Create the PR and report the URL.

# Security review instructions

Check the changes in order against the following angles, and report any
problems found with a severity rating:
- Missing input validation (injection: SQL / command / XSS / SSRF)
- Authentication/authorization gaps (missing permission checks, privilege escalation)
- Secret exposure (hardcoded keys/tokens, output to logs)
- Insecure defaults (excessive exposure, lax CORS, unvalidated redirects)
- Known vulnerabilities in dependencies, insecure crypto / RNG usage

## How to report
- For each finding: location / attack scenario (how it could be exploited) / a concrete fix.
- Flag suspicions you are not certain of as "needs confirmation" (do not silently skip them).
- If there is no problem, state "no issues" along with the angles you checked.

## Things not to do
- Do not generate actual attack code or exploitation steps (show fixes only).

# Docker / infrastructure work rules

## Absolute rules (preventing destruction comes first)
- Do not run destructive commands against production or shared environments on your own
  (`docker system prune`, deleting volumes, `down -v`, etc.).
- Pin images to fixed tags. Do not rely on `latest`.
- Pass secrets via environment variables / secret management.
  Do not bake them into the Dockerfile or image.
- Keep exposed ports and privileges (privileged, etc.) to the minimum necessary.

## Conventions
- Keep Dockerfiles small with multi-stage builds, mindful of layer caching.
- Run as a non-root user.
- After changes, build and start locally to verify before reporting.

## Definition of done
`docker build` passes, the container starts, and the health check / basic
operation can be confirmed.

# Dependency rules

## Absolute rules
- Before adding a dependency, check whether the standard library or an existing
  dependency suffices.
- When adding a new dependency, add a one-line note on its purpose, alternatives,
  and maintenance status.
- Do not bump major versions on your own (only when told to).
- Do not regenerate lock files (package-lock.json, etc.) on your own.
- Avoid packages of dubious origin or with extremely few stars or poor maintenance.

## Steps
1. State the reason for the addition or update.
2. After adding it, confirm the build and tests pass.
3. Confirm the license does not conflict with your use case.

## Definition of done
Build and tests pass after the dependency change, and you can explain the diff in the lock file.