36 lines
2.1 KiB
Markdown
36 lines
2.1 KiB
Markdown
# Agent Instructions
|
|
|
|
## Documentation Maintenance
|
|
|
|
When changing behavior, architecture, or user-facing workflows, update documentation in the same task. Do not defer documentation updates for implemented work.
|
|
|
|
Use `docs/README.md` as the documentation map and keep each fact in one home:
|
|
|
|
| Change type | Update |
|
|
|-------------|--------|
|
|
| Architecture, crate boundaries, or sim/network split | New or updated ADR in `docs/adr/` |
|
|
| Editor framework intent, principles, or non-goals | `docs/mission.md` |
|
|
| Editor feature design or phase status | `docs/editor/` |
|
|
| User controls, run commands, or troubleshooting | Root `README.md` |
|
|
| Shipped feature completion | Root `README.md` implementation checklist |
|
|
| Bevy upgrade policy | ADR 0002 and migration notes in `docs/adr/` |
|
|
| Milestone scope before implementation | `.cursor/plans/` plan file |
|
|
|
|
Create an ADR in `docs/adr/NNNN-short-title.md` when a decision is hard to reverse or affects multiple crates, such as rendering path, scene format, PIE semantics, settings schema, or netcode choice. Use this format: Status, Context, Decision, Consequences. Number ADRs sequentially and link new ADRs from `docs/README.md` and the root README when relevant.
|
|
|
|
Coherence rules:
|
|
|
|
- One home per fact. Link across docs; do not copy paragraphs between README, mission, and ADRs.
|
|
- Intent vs implementation: mission/ADRs explain why, README explains how to use, crate module docs explain local API.
|
|
- Plans vs permanent docs: `.cursor/plans/` holds working roadmaps; promote stable decisions into `docs/` when implemented.
|
|
- Stale docs are bugs. If code contradicts docs, fix both or fix docs in the same PR/task.
|
|
- New subsystems get a short entry in `docs/README.md` and, if editor-facing, `docs/editor/README.md`.
|
|
|
|
End-of-task checklist for relevant implementation work:
|
|
|
|
1. Did behavior or UX change? Update README controls or checklist.
|
|
2. Did architecture or policy change? Update or create an ADR or mission note.
|
|
3. Did an editor workflow change? Update `docs/editor/`.
|
|
4. Added a new doc file? Index it in `docs/README.md`.
|
|
5. Left a deliberate gap? Record it as future work in README or an ADR Consequences section.
|