TORCH/CLAUDE.md

CLAUDE.md — Generic Agent Execution Workflow

This guide defines an execution flow that works across repositories and tech stacks.

Default workflow

1. Load baseline context
   • AGENTS.md
   • CONTRIBUTING.md
   • KNOWN_ISSUES.md
   • docs/agent-handoffs/README.md
   • Recent notes in docs/agent-handoffs/learnings/ and docs/agent-handoffs/incidents/
2. Clarify the task
   • Restate the requested outcome.
   • Identify constraints, risks, and assumptions.
3. Plan minimal changes
   • Keep scope tight.
   • Avoid touching unrelated files.
4. Implement
   • Apply small, reversible edits.
   • Favor readability and maintainability.
5. Validate
   • Run relevant checks for impacted files.
   • Capture exact commands and outcomes.
6. Document and hand off
   • Summarize what changed and why.
   • Record reusable learnings/incidents when appropriate.

Working files for session state

Use the following folders as lightweight coordination artifacts:

• src/context/ — Current objective, scope, constraints.
• src/todo/ — Task checklist and blockers.
• src/decisions/ — Important design/implementation choices.
• src/test_logs/ — Validation commands and results.
• src/issues/ — Investigations or audits that may become tracked issues.

Recommended content templates

Context note template

• Goal
• Scope
• Constraints
• Open questions

Todo note template

• Pending tasks
• Completed tasks
• Blocked tasks

Decision note template

• Decision
• Alternatives considered
• Rationale
• Consequences/follow-ups

Test log template

• Command
• Result (pass/fail/warn)
• Notes (environmental limits, retries, artifacts)

Knowledge-sharing protocol

Where to write durable knowledge

• docs/agent-handoffs/learnings/ for reusable successes.
• docs/agent-handoffs/incidents/ for failures and mitigations.
• KNOWN_ISSUES.md for active, reproducible unresolved issues.

File naming

Use YYYY-MM-DD-short-topic.md.

Required structure for learning/incident notes

1. Context
2. Observation
3. Action taken
4. Validation performed
5. Recommendation for next agents

Quality checklist before completion

• Scope matches request.
• Documentation remains repository-agnostic unless explicitly needed.
• No unsupported claims about testing.
• Assumptions and limitations are called out.
• Changes are easy to revert.

Anti-patterns to avoid

• Embedding product/company-specific guidance in baseline docs.
• Large refactors when a focused change is sufficient.
• Skipping validation without recording why.
• Creating duplicate notes when an update would suffice.

Customization policy

This file should stay generic until real repository-specific patterns emerge. When customizing:

• Add a clearly labeled section: Repository-specific overrides.
• Keep generic workflow unchanged.
• Include evidence (commands, failures, repeated incidents) for each override.