🗂️ ТЗ из множества файлов
Как разбить техническое задание на систему файлов, которую CC читает без потери приоритетов — спека, план, статус, эталоны.
📐
Обзор всей системы документов — на странице Большая проектная документация. Здесь — конкретная методология разбиения ТЗ.
💡 Почему один файл проигрывает пяти
Файл ТЗ на 2000 строк агент читает хуже, чем пять связанных файлов по 200 строк каждый. Дело не в объёме контекстного окна — оно у Claude 5 достаточное. Дело в приоритете: когда «что строим», «в каком порядке» и «что уже сделано» свалены в один текст, агенту приходится каждый раз заново вычленять релевантный кусок из всего документа. У отдельного файла — одна роль: spec.md не меняется от промпта к промпту, todo.md обновляется на каждом шаге. Агент грузит только то, что нужно под конкретную задачу, а не пересканирует всё целиком.
⚠️
Ловушка: файлы без чёткого владельца роли начинают дублировать друг друга и со временем расходятся — требование в
spec.md одно, а в todo.md уже другое. При конфликте агент выбирает версию непредсказуемо: иногда более свежую по контексту диалога, иногда ту, что попалась первой при чтении. Правило простое — у каждого факта одно место хранения, остальные файлы на него только ссылаются.
Файлы multi-file ТЗ
Шесть ролей, которые вместе закрывают то, что раньше пытались утрамбовать в один документ.
| Файл | Роль | Кто обновляет | Когда читает агент |
|---|---|---|---|
spec.md |
ЧТО строим: требования, инварианты, границы | Человек (правки редки, требуют явного согласия) | В начале задачи и при любом сомнении в требовании |
prompt_plan.md |
КАК: фазы, порядок выполнения, зависимости между шагами | Человек или агент — по итогам brainstorming/planning-сессии | Перед стартом фазы, чтобы понять, что делать дальше и от чего это зависит |
todo.md |
ГДЕ мы сейчас: статус шагов, что сделано, что дальше | Агент — после каждого завершённого шага | В начале каждой сессии, чтобы продолжить без пересказа контекста |
INITIAL.md |
Шаблон постановки одной фичи: Feature / Examples / Documentation / Other Considerations | Человек — по одному на фичу перед тем, как отдать её агенту | При старте работы над конкретной фичей |
examples/ |
Эталонные файлы-паттерны: как у нас принято писать компонент, тест, миграцию | Человек — фиксирует паттерн после первой реализации вручную | Перед написанием кода того же типа — агент копирует стиль, а не изобретает |
| ADR | Почему так решили: контекст решения, рассмотренные альтернативы, последствия | Человек (иногда агент — черновик, человек утверждает) | Когда требуется понять мотивацию существующего решения, а не переизобретать его |
Связывание файлов
Два механизма — не взаимозаменяемые, а для разных типов информации.
📥 @import в CLAUDE.md — upfront
- Грузится в контекст каждой сессии автоматически, без запроса
- Подходит для того, что нужно агенту почти всегда: инварианты, границы, соглашения по стилю
- Чем больше файлов заимпортировано upfront, тем дороже каждая сессия по токенам
🔗 Ссылки в тексте — on-demand
- Агент открывает файл только когда до него доходит очередь по ссылке
- Подходит для объёмного и специфичного: examples/, ADR, детали конкретной фазы плана
- Экономит контекст сессии — незадействованные файлы не грузятся вообще
# Проект
@spec.md
@prompt_plan.md
@todo.md
Детали по фичам — в INITIAL.md конкретной фичи (ссылка в todo.md).
Паттерны кода — в examples/, открывай перед написанием нового файла того же типа.От идеи до исполнения
Четыре шага между «есть идея» и «код проверен и слит» — каждый со своим файлом-выходом.
1
Idea honing → spec.md
Диалог с Claude по одному вопросу за раз: что строим, для кого, какие инварианты нельзя нарушать, что явно вне границ. Результат фиксируется в
spec.md — не раньше, чем на все вопросы есть ответ.
2
spec.md → prompt_plan.md
Спека разбивается на фазы по 2-5 минут работы каждая, с исполняемой верификацией на выходе из фазы — не «вроде работает», а конкретная команда или тест, который либо проходит, либо нет.
3
Выполнение по шагам + статус в todo.md
Каждый шаг плана выполняется отдельным промптом. По завершении статус в
todo.md обновляется сразу — это позволяет прерваться и продолжить в новой сессии без пересказа, что уже сделано.
4
Validation gate после каждого шага
Перед переходом к следующему шагу — реальная проверка (тест, линт, ручной прогон), а не доверие отчёту агента «готово». Не прошло — не двигаемся дальше.
Чек-лист: полное ли твоё ТЗ
- ☐ У каждого требования в spec.md есть критерий проверки, который агент не может обойти молча
- ☐ Инварианты (что всегда должно оставаться верным) прописаны явно, а не подразумеваются
- ☐ Границы «что мы НЕ делаем» зафиксированы отдельным пунктом, а не вычисляются от противного
- ☐ На каждый повторяющийся паттерн кода есть файл в examples/
- ☐ Между spec.md, prompt_plan.md и todo.md нет противоречий — факт хранится в одном месте
- ☐ todo.md отражает актуальный статус, а не состояние недельной давности
💡
Формат INITIAL.md — шаблон постановки фичи
Подход Cole Medin: перед тем как отдавать фичу агенту, оформи её одним небольшим файлом из четырёх секций. Это не замена spec.md, а промежуточный слой — конкретная фича внутри общего проекта.
- Feature — что нужно сделать, одним-двумя абзацами, без технических деталей реализации
- Examples — ссылки на файлы в examples/, которые задают стиль и паттерн для этой фичи
- Documentation — ссылки на актуальную документацию библиотек, которые фича затрагивает
- Other Considerations — всё, что не влезает в первые три пункта: ограничения окружения, известные подводные камни, что уже пробовали и не сработало
Из INITIAL.md агент собирает подробный PRP (Product Requirements Prompt) — по сути расширенную версию фичи с планом реализации, который затем проходит через собственные validation gates.
Один файл vs множество
| Ситуация | Достаточно одного project-brief | Нужна система из файлов |
|---|---|---|
| Размер задачи | Одна фича или небольшой скрипт, укладывается в пару экранов текста | Проект из нескольких модулей, рассчитан на дни или недели работы |
| Число сессий | Одна-две сессии до готового результата | Много сессий, работа прерывается и возобновляется |
| Повторяемость паттернов | Код не повторяет сам себя, каждый файл уникален | Есть повторяющиеся паттерны (компоненты, эндпоинты, миграции) — нужны examples/ |
| Команда | Один человек держит весь контекст в голове | Несколько человек или сессий — нужна общая точка правды, а не память одного участника |
| Что использовать | Подготовка к проекту — один файл ТЗ | spec.md / prompt_plan.md / todo.md / examples/ / ADR |
🧭
Консенсус практиков: разбивай работу на маленькие проверяемые шаги и фиксируй спеку до того, как агент начнёт писать код — переделать план дёшево, переделать код дорого.
— так делают Harper Reed, Cole Medin, obra / Superpowers и Mitchell Hashimoto (шпаргалка).
Лайфхаки
💡
Лайфхак: один промпт — одна задача из todo.md. Не проси агента «сделать фазу 2 и заодно прибраться в фазе 3» — это ломает атомарность шага и усложняет откат при ошибке.
💡
Лайфхак: прежде чем стартовать выполнение, спроси Claude: «какие противоречия ты видишь в spec.md?» — модель неплохо находит нестыковки между требованиями, если явно попросить их поискать, а не полагаться, что она сообщит о них сама.
💡
Лайфхак: обновляй examples/ сразу при смене паттерна. Устаревший пример в этой папке агент скопирует буквально — и разнесёт устаревший стиль по всем новым файлам того же типа.
💡
Лайфхак: todo.md — это то, что снимает необходимость пересказывать контекст в начале новой сессии. Если приходится каждый раз объяснять агенту, на чём остановились, — значит, todo.md не обновляется вовремя.
💡
Лайфхак: привязывай фазы prompt_plan.md к атомарным коммитам — один завершённый и провалидированный шаг плана превращается в один коммит, что делает историю git читаемой и откат точечным.