mirror of
https://github.com/PR0M3TH3AN/TORCH.git
synced 2026-10-27 16:01:54 +00:00
113 lines
3.4 KiB
Markdown
113 lines
3.4 KiB
Markdown
# AGENTS.md — Repository-Agnostic Agent Operating Guide
|
|
|
|
This file defines how agents should work in this repository **before any project-specific customization exists**.
|
|
|
|
## Purpose
|
|
|
|
- Keep agent work predictable, auditable, and safe.
|
|
- Minimize repeated discovery work across sessions.
|
|
- Capture durable learnings so future agents can move faster.
|
|
|
|
## Session startup checklist (run every session)
|
|
|
|
1. Read `AGENTS.md`.
|
|
2. Read `CLAUDE.md` for execution workflow details.
|
|
3. Read `CONTRIBUTING.md` for commit and PR expectations.
|
|
4. Read `KNOWN_ISSUES.md` for active blockers and workarounds.
|
|
5. Read `docs/agent-handoffs/README.md`.
|
|
6. Scan recent notes in:
|
|
- `docs/agent-handoffs/learnings/`
|
|
- `docs/agent-handoffs/incidents/`
|
|
7. If present, review the current run artifacts in:
|
|
- `src/context/`
|
|
- `src/todo/`
|
|
- `src/decisions/`
|
|
- `src/test_logs/`
|
|
- `src/issues/`
|
|
|
|
## Core operating principles
|
|
|
|
- Default to generic guidance and neutral language.
|
|
- Make the smallest safe change that satisfies the request.
|
|
- Avoid unrelated refactors.
|
|
- Preserve backward compatibility unless explicitly asked otherwise.
|
|
- Prefer explicit commands and documented behavior over assumptions.
|
|
- Record assumptions clearly in your final summary.
|
|
|
|
## Validation policy
|
|
|
|
- Run the most relevant checks for changed files (tests, lint, typecheck, build, or targeted scripts).
|
|
- Never claim a check passed unless it was actually executed.
|
|
- If a check cannot run, record:
|
|
- command attempted,
|
|
- why it could not complete,
|
|
- what fallback validation was performed.
|
|
|
|
## Knowledge-sharing protocol
|
|
|
|
### What belongs where
|
|
|
|
- `KNOWN_ISSUES.md`
|
|
- Active, reproducible issues only.
|
|
- Include status, impact, workaround, and last verification date.
|
|
- `docs/agent-handoffs/learnings/`
|
|
- Proven patterns, repeatable fixes, and successful implementation guidance.
|
|
- `docs/agent-handoffs/incidents/`
|
|
- Failures, root causes, mitigations, and prevention guidance.
|
|
- `src/context/`
|
|
- Snapshot of current task context (goal, scope, constraints).
|
|
- `src/todo/`
|
|
- Actionable checklist for in-progress work.
|
|
- `src/decisions/`
|
|
- Key implementation decisions and rationale.
|
|
- `src/test_logs/`
|
|
- Commands run and their outcomes.
|
|
- `src/issues/`
|
|
- One-off investigative or audit outputs not yet promoted to `KNOWN_ISSUES.md`.
|
|
|
|
### Naming standard (generic)
|
|
|
|
Use: `YYYY-MM-DD-short-topic.md`
|
|
|
|
Examples:
|
|
|
|
- `2026-02-14-validation-before-summary.md`
|
|
- `2026-02-14-missing-baseline-context.md`
|
|
|
|
Naming rules:
|
|
|
|
- Keep names concise and descriptive.
|
|
- Avoid company, product, team, customer, and environment names.
|
|
- Prefer neutral technical terms.
|
|
|
|
### Required sections for reusable notes
|
|
|
|
Use these headings in learning/incident notes:
|
|
|
|
1. Context
|
|
2. Observation
|
|
3. Action taken
|
|
4. Validation performed
|
|
5. Recommendation for next agents
|
|
|
|
### Update decision tree
|
|
|
|
When you discover reusable context:
|
|
|
|
1. Check if an existing note already covers it.
|
|
2. If yes, update that note.
|
|
3. If no, add a new note in `learnings/` or `incidents/`.
|
|
4. If the issue is still active/reproducible, add or update `KNOWN_ISSUES.md`.
|
|
|
|
## Priority order when guidance conflicts
|
|
|
|
1. System/developer/user instructions in the active session
|
|
2. `AGENTS.md`
|
|
3. `CLAUDE.md`
|
|
4. `CONTRIBUTING.md`
|
|
5. Inline code comments and prompt templates
|
|
|
|
## Keep this file generic
|
|
|
|
Only add project-specific details after they are truly needed and explicitly labeled as repository-specific.
|