# AGENTS.md — точка входа агентов проекта {{PROJECT_NAME}}

Карта документации и правила её ведения. Любой агент читает этот файл **сразу после**
`CLAUDE.md` (паспорта) и **до** начала работы.

## Карта документации

| Документ | Что в нём | Когда читать | Когда обновлять |
|----------|-----------|--------------|-----------------|
| `CLAUDE.md` | паспорт: стек, команды, среды, правила | ВСЕГДА, первым | при изменении стека/команд/правил |
| `AGENTS.md` | этот файл: карта доков | ВСЕГДА, вторым | при изменении состава доков |
| `README.md` | витрина: что это, quickstart | при онбординге в задачу | при изменении quickstart/обзора |
| `docs/ARCHITECTURE.md` | код-карта, потоки, БД | перед изменением кода | при изменении компонентов/API/БД |
| `docs/PIPELINE.md` | стадии, Quality Gates, агенты | при вопросах процесса | при изменении процесса |
| `docs/PRODUCT_VISION.md` | зачем проект, ценность | при продуктовых решениях | при смене видения |
| `docs/operations/INFRA.md` | топология, env, границы, риски общего хоста | перед deploy/инфра-работой | при изменении топологии/env |
| `docs/architecture/adr/` | сквозные ADR | перед архитектурным решением | новый сквозной ADR |
| `docs/work-items/<id>/` | артефакты конкретной задачи | свою задачу — всегда | по своей стадии |
| `docs/_templates/` | скелеты номерных доков (канон) | перед записью номерного дока | НЕ править локально |
| `docs/_standards/` | PIPELINE_DOCS / HANDOFF_PROTOCOL / TRACEABILITY (канон) | по ссылкам из промптов | НЕ править локально |
| `CHANGELOG.md` | история изменений | — | каждый PR с изменением функционала |

## Правила ведения

1. **Артефакты задач** пиши ТОЛЬКО в `docs/work-items/<id>/` по стандарту
   `docs/_standards/PIPELINE_DOCS.md`; скелеты бери из `docs/_templates/` (не угадывай структуру).
2. **Машинные вердикты** — строго YAML-frontmatter; имена/регистр ключей не менять
   (`docs/_standards/HANDOFF_PROTOCOL.md`).
3. **Документация = golden source.** Изменил код → обнови `docs/ARCHITECTURE.md` /
   `README.md` / `CHANGELOG.md` в том же PR. Reviewer обязан вернуть PR без обновлённой доки.
4. **ADR.** Архитектурные решения фиксируются в `docs/work-items/<id>/06-adr/`; сквозные — в
   `docs/architecture/adr/adr-NNNN-slug.md` (реестр — `docs/architecture/adr/README.md`).
5. **Трассировка.** Нетривиальный инвариант в коде помечается маркером
   `{{WORK_ITEM_PREFIX}}-NNN`; правка чужого маркера — только после чтения его ADR
   (`docs/_standards/TRACEABILITY.md`).
6. **Канон не форкается.** `docs/_templates/` и `docs/_standards/` — копия живого канона
   оркестратора на момент онбординга; их обновление приходит отдельными PR, локально не править.