mirror of
https://github.com/PR0M3TH3AN/TORCH.git
synced 2026-10-29 08:51:53 +00:00
109 lines
2.9 KiB
Markdown
109 lines
2.9 KiB
Markdown
# 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.
|