4.0 KiB
Agent Rules v1
1. Evidence-first
Агент должен формировать документацию только на основе подтвержденных источников: кода, существующей документации, системной аналитики и других явно доступных артефактов. Нельзя додумывать поведение системы, зависимости или бизнес-логику, если они не подтверждаются исходными материалами.
2. One Stable Object = One Document
Каждый документ должен описывать только одну устойчивую техническую сущность или один устойчивый аспект системы. Если по сущности могут ссылаться другие документы или она может переиспользоваться, ее нужно выносить в отдельный документ.
3. No Semantic Duplication
Документы не должны пересекаться по смыслу и повторять одно и то же содержание. Если одна и та же логика, правило или описание нужны в нескольких местах, агент должен вынести их в отдельный документ и использовать ссылки вместо дублирования текста.
4. Explicit Document Type
Для каждого документа агент должен явно определять его тип. На базовом уровне нужно использовать типы ui_page, api_method, logic_block и применять для каждого типа свой шаблон содержания и набор метаданных.
5. Hierarchical File Structure
Агент должен строить документацию как иерархию каталогов и файлов, а не как плоский набор страниц. Документы нужно раскладывать по смысловым разделам, например docs/ui, docs/api, docs/logic, docs/architecture, чтобы структура отражала архитектуру и упрощала навигацию.
6. Required YAML Frontmatter
Каждый документ должен начинаться с единообразного YAML frontmatter. В нем обязательно должны быть базовые метаданные документа: стабильный id, title, doc_type, status, source_of_truth, а также ссылки на связанные документы и кодовые артефакты.
7. Correct Internal Decomposition
Содержимое документа должно следовать шаблону своего типа и быть правильно декомпозировано внутри самого документа. Сценарии работы нужно описывать отдельно от детальных правил, контрактов, ограничений и дополнительных требований, чтобы документ оставался читаемым, атомарным и пригодным для индексирования.
8. Explicit Links Between Code and Docs
Каждый документ должен быть явно связан как минимум с соответствующим кодом и с соседними документами, если такие связи существуют. Агент должен фиксировать эти связи в метаданных и в тексте документа, чтобы документация образовывала связанную систему знаний, а не набор изолированных файлов.