📐 Большая проектная документация
Система документов среднего-крупного проекта, которую CC читает как источник правды — от PRD до examples/. Не бюрократия ради галочки, а контекст-система: агент знает о проекте ровно то, что ему явно показали, и ни байтом больше.
У человека-разработчика есть память о прошлых решениях, ощущение архитектуры проекта, интуиция «так тут не принято». У агента этого нет — на старте каждой сессии он видит только то, что загружено в контекст: файлы, на которые сослались, документы, которые прочитал. Большая проектная документация — это не описание проекта «для истории», а рабочий контекст-слой: PRD объясняет зачем, spec фиксирует что, PLAN — в каком порядке, ADR — почему так, а не иначе, examples/ — как именно писать код здесь. Возьмём сквозной пример: CRM под ключ — REST API, БД, фронт. Без карты документов агент на третьей неделе разработки не будет знать, почему авторизацию сделали через отдельный сервис, а не встроили в основной бэкенд — и с шансами предложит «улучшение», разрушающее это решение.
Группа «Проектирование»
Эта страница — хаб группы. Дальше три страницы с конкретными методиками:
Карта документов проекта
Полный набор для среднего-крупного проекта. Не всё нужно с первого дня — см. чек-лист ниже по размеру проекта.
| Документ | Назначение | Кто пишет | Когда обновляется |
|---|---|---|---|
| PRD (Product Requirements Doc) | Зачем продукт нужен и для кого — бизнес-контекст, пользовательские сценарии, метрики успеха | Человек (продакт/тимлид), Claude помогает структурировать | Редко — при смене бизнес-целей или объёма продукта |
| spec.md | Что именно строим технически — функциональные требования, инварианты, границы системы, что не входит в объём | Человек + Claude в диалоге (brainstorming/spec-режим) | При изменении требований к фиче или модулю |
| prompt_plan.md / PLAN.md | Порядок работы — фазы, зависимости между шагами, что делать в каждой сессии | Claude по итогам spec, человек утверждает | После каждой завершённой фазы; при пересмотре порядка |
| ADR (Architecture Decision Record) | Архитектурные решения и обоснование — почему выбрали именно так, какие альтернативы отклонили | Человек (архитектор/тимлид), по одному ADR на решение | При каждом неочевидном архитектурном выборе, задним числом не переписывается |
| examples/ | Эталонные паттерны кода — как здесь принято писать контроллер, тест, компонент; сильнее любого текстового описания стиля | Человек курирует, добавляет лучшие реализации по факту | Когда появляется новый паттерн, который стоит закрепить как образец |
| glossary | Термины домена — что в этом проекте значит «заказ», «сессия», «активный клиент», чтобы не было двух трактовок | Человек, по мере появления неоднозначных терминов | При введении нового термина или конфликте трактовок в коде |
Как агент читает документацию
Не вся документация грузится одинаково — часть в контексте с первой секунды сессии, часть подтягивается по требованию задачи.
CLAUDE.mdв корне проекта — читается автоматически при старте сессии- Директивы
@importвнутри CLAUDE.md — подтягивают glossary, дев-стандарты, критичные инварианты - Только компактное, часто нужное: конвенции, команды, запреты — не вся документация целиком
- spec.md конкретного модуля — читается, когда задача касается именно этого модуля
- ADR — открывается, когда агент упирается в архитектурное решение и нужно понять «почему так»
- examples/ — конкретный файл-образец, релевантный текущему паттерну (не вся папка целиком)
Порядок чтения обычно такой: CLAUDE.md → PLAN.md (текущая фаза) → spec.md релевантного модуля → примеры из examples/ → при необходимости конкретный ADR. Такой порядок экономит контекстный бюджет: агент не тратит окно на PRD и glossary целиком, если задача — точечный багфикс в уже понятном модуле.
Минимальный набор доков под размер проекта
Полная карта документов из шести штук — это для крупного проекта. Не переусложняй маленький.
| Размер проекта | Минимальный набор | Когда расширять |
|---|---|---|
| Маленький (скрипт, лендинг, MVP на выходные) | CLAUDE.md + план в голове разработчика (можно не записывать) |
Если проект пережил первую неделю и обрастает фичами — переходи к среднему набору |
| Средний (рабочее приложение, команда 1-3 человека) | CLAUDE.md + spec.md + PLAN.md |
Появляются неочевидные архитектурные развилки → добавляй ADR по одному под каждое решение |
| Крупный (CRM/платформа, несколько модулей, команда) | Полная карта: PRD + spec + PLAN + ADR + examples/ + glossary | Уже максимум — дальше делить документацию по модулям, не по типам |
- ☑ Маленький проект: не пиши PRD и ADR ради процесса — это чистые накладные расходы без пользы
- ☑ Средний проект: как только появляется спорное архитектурное решение — заведи первый ADR, не жди «пока не накопится»
- ☑ Крупный проект: заведи examples/ с первого дня — новые паттерны кода добавлять дешевле, чем потом объяснять словами
- ☑ На любом размере: если документ никто не открывал три месяца — либо он лишний, либо устарел и вводит агента в заблуждение
🧭 Консенсус практиков: спецификация и план — ДО кода, а не как документация постфактум. Harper Reed формализовал цепочку spec → plan → todo как основной рабочий цикл с агентом. Cole Medin добавляет к этому INITIAL.md и examples/ — паттерн PRP (Product Requirement Prompt), где примеры кода важнее описаний. Mitchell Hashimoto настаивает на scaffolding-документации как способе задать границы работы агента заранее, а не разгребать после. Hrishi Olickel — сторонник ADR как обязательной практики: без записанного «почему» агент рано или поздно «улучшит» архитектуру обратно в то, от чего вы уже отказались. Сводка по всем подходам — на странице шпаргалки.
Лайфхаки
todo.md, а не в голове или в чате. При обрыве сессии — по сбою, лимиту или просто закрытому терминалу — агент открывает todo.md и продолжает с места остановки, а не переспрашивает контекст заново.