125 lines
3.6 KiB
Markdown
125 lines
3.6 KiB
Markdown
# Claude Instructions
|
|
|
|
## Project Documentation
|
|
|
|
The product requirements are defined in `PRD.md`.
|
|
|
|
When planning or implementing features:
|
|
- Treat `PRD.md` as the source of truth for product behavior.
|
|
- If a task conflicts with `PRD.md`, stop and report the conflict.
|
|
- If a task introduces behavior not covered by `PRD.md`, explicitly identify the gap.
|
|
|
|
Documentation priority:
|
|
|
|
1. Task Brief
|
|
2. PRD.md
|
|
3. Existing code
|
|
|
|
If there is a conflict:
|
|
Task Brief > PRD.md > Existing code
|
|
|
|
Always report conflicts before implementing.
|
|
|
|
## Working style
|
|
|
|
- Prefer small, focused changes.
|
|
- Do not refactor unrelated code.
|
|
- Do not change public behavior outside the task scope.
|
|
- For non-trivial tasks, plan before editing.
|
|
- If no code change is needed, stop and explain why with evidence.
|
|
- If requirements are ambiguous, list assumptions and choose the safest minimal default.
|
|
- If any decision is not clearly instructed, stop and ask the user before proceeding.
|
|
- When resolving Ruby, Rails, or Tailwind CSS questions, use the Context7 MCP tool — do not rely on training data.
|
|
- Always use `bin/rails generate` to create artifacts (models, controllers, migrations, etc.) instead of crafting files manually.
|
|
- Keep generated artifacts in `.agent/tasks/<task-id>/` when the task is medium or larger.
|
|
|
|
## Task lanes
|
|
|
|
Use the smallest lane that fits the work.
|
|
|
|
### Fast lane
|
|
Use for obvious one-file changes, typos, small logging changes, or simple renames.
|
|
|
|
Workflow:
|
|
1. Implement directly.
|
|
2. Run the smallest relevant verification.
|
|
3. Show the diff.
|
|
|
|
### Standard lane
|
|
Use for most product changes and bugs.
|
|
|
|
Workflow:
|
|
1. Explore relevant code.
|
|
2. Produce a concise plan.
|
|
3. Wait for approval before editing.
|
|
4. Implement the approved plan.
|
|
5. Run verification.
|
|
6. Review the diff.
|
|
7. Fix only accepted blockers/warnings.
|
|
|
|
### Cautious lane
|
|
Use for authentication, authorization, billing, payments, user data, migrations, concurrency, infrastructure, or broad refactors.
|
|
|
|
Workflow:
|
|
1. Create or update `.agent/tasks/<task-id>/brief.md`.
|
|
2. Explore read-only.
|
|
3. Produce a plan.
|
|
4. Review the plan adversarially before editing.
|
|
5. Implement in small steps.
|
|
6. Run all relevant verification.
|
|
7. Review the diff in a fresh context.
|
|
8. Fix only accepted blockers/warnings.
|
|
|
|
## Verification
|
|
|
|
Before considering a task complete, run relevant project checks. Prefer commands declared by the project, such as:
|
|
|
|
- test command
|
|
- lint command
|
|
- typecheck command
|
|
- build command
|
|
|
|
If a command is unavailable, say so explicitly. Never claim a command passed unless it was run in this session and its output was inspected.
|
|
|
|
## Planning output
|
|
|
|
For non-trivial tasks, produce a plan with:
|
|
|
|
- task classification: Fast, Standard, or Cautious;
|
|
- assumptions;
|
|
- files inspected;
|
|
- files likely to change;
|
|
- files that should not change;
|
|
- implementation steps;
|
|
- tests to add or update;
|
|
- verification commands;
|
|
- risks and ambiguities;
|
|
- stopping conditions.
|
|
|
|
Wait for approval before editing.
|
|
|
|
## Review policy
|
|
|
|
Before finalizing Standard or Cautious tasks, review the diff against the task brief and approved plan.
|
|
|
|
Report real issues only:
|
|
|
|
- bugs;
|
|
- missing requirements;
|
|
- missing tests;
|
|
- regressions;
|
|
- security risks;
|
|
- data consistency risks;
|
|
- concurrency/idempotency risks;
|
|
- out-of-scope changes.
|
|
|
|
Avoid subjective style comments unless they affect correctness or maintainability.
|
|
|
|
## Git
|
|
|
|
- Work on a dedicated branch for non-trivial tasks.
|
|
- Keep commits focused.
|
|
- Show `git diff` before committing.
|
|
- Never force push unless explicitly instructed.
|
|
- Do not commit secrets, `.env` files, local databases, logs, or generated dependency folders.
|