66 lines
3.4 KiB
Markdown
66 lines
3.4 KiB
Markdown
# AGENTS.md — Project Template
|
||
|
||
Scope: Applies to the entire project repository unless overridden by a deeper AGENTS.md.
|
||
|
||
This file is copied by scaffolding into new projects. Edit to suit the project while keeping the one-way collaboration flow and file-first practices.
|
||
|
||
## Collaboration Artifacts
|
||
- Root: `collab/`
|
||
- Subdirectories: `collab/questions/`, `collab/proposals/`, `collab/plan/`
|
||
- Naming per round: `NN-<subject>.md` (+ `.llm.md` sibling)
|
||
- One-way sequence: Questions → Proposal → Plan → Implement; no backsteps after approval
|
||
- Agent reads `.llm.md`; humans edit `.md`. Agent writes both siblings.
|
||
|
||
## Logs and Docs
|
||
- `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md` — update each meaningful change.
|
||
- `docs/` for feature docs and ADRs.
|
||
- Keep `README.md` current.
|
||
|
||
## Chat Output Policy
|
||
- Default: `Updated <filepath>. Read/edit and let me know.`
|
||
- Keep chat ≤5 lines; no diffs; announce only collab file changes; log details in DevLog.
|
||
- Quiet shell: avoid printing file contents/diffs; prefer silent checks and DevLog summaries.
|
||
- Quiet is mandatory (no toggle) in this workflow.
|
||
- Tool logging: prefer a quiet wrapper that logs to `docs/devlog/tool.log` on failures; keep chat silent.
|
||
|
||
## Coding, Tests, and Git
|
||
- Minimal, focused changes; adopt TDD (write tests first) and require unit/integration tests for all features; consistent style.
|
||
- Conventional Commits; branch `main`; tags `YYYY-MM-DD-HHMM` when warranted.
|
||
|
||
## Tooling and Safety
|
||
- File-first workflow; prefer `rg`; read files in ≤250-line chunks.
|
||
- Respect sandbox/approvals; avoid destructive actions without confirmation.
|
||
- Provide brief preambles before grouped/long-running commands.
|
||
|
||
## Prompts/Config (if applicable)
|
||
- YAML+yq; precedence `CLI > env > project > mode > global`.
|
||
- Prompt order: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
|
||
- Outputs: `<project>/runs/<timestamp>/...`; require `--force` for overwrites; never `git push`.
|
||
|
||
## Governance and Propagation
|
||
- When you adopt a reusable, non-project-specific practice, reflect it in your project’s system prompt and AGENTS.md to keep them aligned. Log such changes in `docs/devlog/`.
|
||
|
||
## Zero Technical Debt, Production-Ready Always
|
||
- Safety first; speed second. No technical debt, ever.
|
||
- Do not defer tests, docs, or clarity/maintainability refactors.
|
||
- Practice TDD (tests first) and keep docs up to date with changes.
|
||
|
||
## Planning and Architecture
|
||
- Plan ahead via Questions → Proposal → Plan to align before coding.
|
||
- Maintain an architecture/module map and clear module boundaries.
|
||
- Implement module-by-module; refactor only when new information requires plan/doc updates.
|
||
|
||
## Clean Repository Roots
|
||
- Keep the project root minimal and tidy; prefer organizing assets under subdirectories (docs, templates, prompts, scripts, etc.).
|
||
|
||
## .gitignore Housekeeping
|
||
- Include and maintain a `.gitignore` with `runs/` and common OS ignores.
|
||
|
||
## CI and Containers (Gitea + Docker)
|
||
- Use Gitea Actions for CI (`.gitea/workflows/`) with local parity via Docker Compose.
|
||
- Perform work inside containers when appropriate; reserve host for git/tea and Docker orchestration.
|
||
- Manage dependencies via Docker images; avoid host installs.
|
||
- Use explicit container/network names and clean up artifacts (`down -v --remove-orphans`).
|
||
## Audits
|
||
- Run regular audits; prompt before release/tags. Save reports under `docs/audits/` and summarize in DevLogs.
|