characterization-tool-for-git-workflows/CLAUDE.md

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.