SDD в организации и в Solo‑проекте

Сейчас многие организации переходят не просто к «агентской разработке», а к SDD (Spec‑Driven Development) и перестраивают SDLC вокруг него. У Anthropic вышла хорошая статья на тему реорганизации процессов вокруг агентов, поэтому данный текст разбит на две части:

1. SDD в организации — объяснение подходов, которые предлагает Anthropic, и того, как они ложатся в уже существующие процессы

2. SDD в solo‑проекте — как у меня получилось выстроить свой процесс SDD, используя две подписки (суммарно на 30$), чтобы разрабатывать пет‑проект и не улетать за лимиты.

Если ты знаком с SDD и текстом Anthropic, можешь пропустить первую половину и сразу перейти ко второй =)

SDD в организации

Новый SDLC предлагает парадигму артефактов: intent.md → spec.md → plan.md → report.md → review.md, которые описаны человеческим языком. Жизнь фичи может посмотреть любой: от идеи до реализации — и понять, какие решения были приняты и на какие компромисы пришлось пойти.

Этап первый — Идея (intent.md)

Anthropic предлагают создать артефакт, в котором нужно отразить:

Intent (что хочется), Problem (что сейчас не так), Proposed outcome (чего хочется достичь), Affected (какие системы затрагиваются), Constraints (какие есть ограничения) и Open questions (на какие вопросы нужно ответить).

По сути, это тот же тикет в Jira/Tracker, который вы видели множество раз. Основная разница в том, что он должен придерживаться более строгого формата и должен делаться вместе с агентом. 

Почему?

Каждый, кто хотя бы немного работал в любой организации, знает, как сложно добиться от другого человека ответа на вопросы: «А чего ты хочешь? А зачем это?» Агент на этом этапе экономит время PO и dev‑команды на выяснение этого. Он общается с заказчиком фичи/аналитиком, и результатом их работы становится стандартизированный артефакт, который можно или передать дальше, или отправить на доработку с новыми вводными.
Также агент обладает доступом к другим артефактам (например, прошлым решениям или коду), что позволяет ему изначально предложить идею, формат которой уже будет вписываться в продукт.

Этап второй — Дизайн (spec.md)

После того как идея была принята, её нужно задизайнить с учётом существующей архитектуры, нюансов безопасности и дизайна. На этом этапе цена ошибки минимальна (мы все ещё не начали писать код), поэтому PO должен гонять спеку столько раз, сколько нужно, пока результат не будет его полностью удовлетворять.

Пример промпта из статьи Anthropic:

Read the attached intent.md and produce a requirements and design spec for integrating it into our existing codebase. Apply the skills available to you so the plan conforms to our brand guidelines, security policies and UX standards. Document the spec fully as spec.md, ready to hand to the engineering team. Describe clearly any areas of concern, especially where you cannot satisfy contradicting policies.

Этап третий — Разработка (plan.md)

Тут уже идея (intent.md) и дизайн (spec.md) доходят до команды разработки. На основе этих документов создается план (plan.md) с описанием работы для агентов. Поскольку мы все ещё не пишем код, план должен проходить ревью столько раз, сколько потребуется, пока разработчик не будет доволен планом и не утвердит его. 

Пример плана:

# Plan: claims status self-service (from intent.md 2026-06-02) ## Files that change portal/src/claims/StatusPanel.tsx (new), claims-api/routes/status.py, claims-api/tests/test_status.py ## Order of work 1. Add the status endpoint behind existing auth. 2. Panel against the endpoint. 3. Wire into the portal nav. ## Risks The claims-core API rate-limits at 50 rps; the panel must cache. ## Proof test_status.py covers the four claim states; screenshot matches the approved mock.

Результатом данного этапа становится plan.md. Когда он принят, агент начинает работать, и уже результатом работы становится report.md (но о нем позже), когда все тесты и детерминированные проверки пройдены. Кстати, про тесты.

Этап четвертый — Тесты (feedback‑loop/report.md)

Агенты могут писать огромное количество кода за единицу времени. Мы (люди) никогда не сможем перерабатывать такие объемы, поэтому прежде чем отдавать результат человеку, агент должен проверить себя сам, а только потом передавать результат дальше по цепочке.
Для таких проверок лучше всего подходят детерминированные проверки: линтеры, тесты, статический анализ кода. Потому что LLM недетерминирована и при разработке может решить одну задачу множеством способов. Линтеры, unit‑тесты и статанализ прекрасно поймают совсем уж плохой результат. А учитывая, что сейчас писать тесты крайне дешево — не иметь их уже неприлично.

Пример блока тестирования в CLAUDE.md:

(CLAUDE.md verification block) ## Verifying your work - Build: make build (must finish with "Build succeeded") - Test: make test (all green; never skip or delete a failing test) - Lint: make lint (zero warnings) Run all three before reporting any task complete, and paste the output. If a test fails, fix the code, not the test.

Результатом этого этапа становится report.md, который читает разработчик. Это отчет агента по проделанной работе, где опытный глаз может заметить странности и попросить их исправить или объяснить. 

Этап пятый — Ревью и подготовка к деплою (review.md)

Скорее всего, каждый, кто это читает, или пытался автоматизировать ревью кода, или видел, как это пытались сделать. Никто не любит эту часть, но по итогу её стало ещё больше, так как кода стало ещё больше.
Основная ошибка в том, что ревью проходит так же, как когда код писали не агенты, из‑за чего процесс захлёбывается. Идея Anthropic — уйти от построчной проверки и перейти на более высокий уровень абстракции: решает ли изменение задачу и какие риски оно несет? Тем самым внимание человека начинает фокусироваться на важных пунктах, а остальные или принимаются как компромисс, или исправляются, или отправляются в backlog/intent.md (см. шаг первый).

Anthropic предлагают следующий пример инструкций по ревью:

# Review instructions ## Passes Run three passes and tag each finding with its pass: - Bugs: logic errors, broken edge cases, subtle regressions - Security: injection risks, authentication gaps, PII in logs - Compliance: the change matches spec.md, plan.md and our design principles ## What Important means here Reserve Important for findings that would break behavior, leak data or breach a policy. Style and naming are nits. ## Cap the nits Report at most five nits per review; summarize the rest as a count. ## Do not report Generated files under src/gen/ and anything CI already enforces.

Также стоит добавить, что мы не говорим тут о критической инфраструктуре. Одно дело, когда мы правим блок, который не так важен системе, и совершенно другое, когда мы правим блок «обработки платежей», например. Там человеческое ревью все ещё нужно и может быть крайне полезным. Но вы не каждый день исправляете и меняете критические компоненты, верно?

Этап шестой — Поддержка

Если вы помните, любой запрос начинается с идеи (intent.md). Но агент сам может её создавать на основе детерминированной аналитики (например, количества ошибок 500 на проде), тем самым замыкая loop и превращая это в SDLC. А для мелких и некритичных задач, возможно, в будущем даже человек не будет нужен.

SDD на solo‑проекте

Гонять спеки туда‑сюда весело и просто, когда за токены платишь не ты, а компания. Тогда становится в общем‑то все равно, какая модель какую задачу решает — желательно, чтобы качественно и прод не лег.
Совершенно другое, когда ты платишь за модели из собственных карманов. Меня, честно, душит жаба отдавать 200$ и получить бан или не использовать модели на полную и не отбить каждую копейку. Да и как‑то получается слишком жирно для будущей open‑source тулзы, которая пока нужна только мне.

Чтобы минимизировать стоимость, я выбрал подписку на Claude за 20$ и OpenCode за 10$, и оказалось, что с этим можно очень комфортно работать, если подходить к этому правильно.

Подготовка до первой строчки кода

Прежде чем вообще начинать что‑то писать с агентами, я подготовил несколько файлов:

• product-brief.md — отвечает за описание продукта — что это должно быть, как хранятся данные, какие этапы (что делаем сейчас, что переносим на потом, а что вне скоупа)

• mvp-done.md — чек‑лист, который отвечает за то, чтобы разработка не стала уходить в дебри. Этапы, указанные в product-brief.md, превращаются в уже осмысленные пункты. Пример из этапа, связанного с UX/UI:

- [ ] Новый дизайн применён ко всем экранам; макеты согласованы пользователем (T-301, T-302)

• backlog.md — по сути, это сборка intent.md в одном месте, но теперь у каждой таски указаны модель, которая пишет план, и модель, которая его реализует (Важно, что агенты не имеют права править backlog.md, чтобы не разудвать план разработки) Пример:

| ID | Task | Plan | Build | После | Status || T-302 | UI: применить дизайн к дереву, панели деталей, баннерам и диалогам | S | K2 | T-301 | todo |

• later.md — файл хранит в себе пожелания, которые появились во время разработки, но выходили за скоуп задачи или этапа. По сути, те же самые intent.md, но необязательные для основного плана

• handoff.md — мостик между сессиями, но об этом позже

Также я отдельно вынес правила для агентов по бюджету, чтобы они не спавнили множество sub‑агентов и не вылетали за квоту, и ограничил выбор моделей. Отдельно была создана папка decisions, которая хранит в себе ADR по проекту.

Смысл этих файлов не в том, чтобы агент написал побольше документации. Они задают границы: что делаем сейчас, что считаем готовым и куда складываем всё интересное, что не входит в текущую задачу.

Workflow

Задача из backlog → контекст и интервью → план → моё ревью →реализация другой моделью → проверки → отчёт → моё ревью → handoff

Агент принимает задачу на планирование определённой таски (планирование я отдал Claude Opus или Sonnet в зависимости от сложности). Читает handoff.md, таску из backlog.md, релевантные ADR из папки decisions и mvp-done.md, после изучает код. Затем, исходя из собранной информации, если есть вопросы без ответа (которые не закрывают сама задача и ADR), проводит интервью, используя grilling (он также ограничен по количеству вопросов, чтобы не сжирать все токены).

Результатом работы является plan.md (планы сохраняются в свою папку после принятия), который я отсматриваю сам через plannotator. Где‑то в 85–90% случаев план норм, но иногда нужно вносить коррективы. Внутри плана лежат описания разделов:

Проблемы, Решения из интервью, Решение, Критерии приёмки, Файлы, Шаги реализации, Тесты, Вне рамок задачи (это часто уходит в later.md) и Риски+вопросы.

Сам план может пересматриваться полностью только 2 раза. После этого агент задаёт на каждый мой комментарий один вопрос формата «делаем/не делаем (заносим в later.md)». Создано это для того, чтобы оно не превращалось в бесконечный loop.

Когда план согласован, он передаётся другой модели через handoff.md, в котором описано (кратко): Текущее состояние, Следующий шаг (возьми вот этот план и реализуй) и Риски. Модель получает handoff.md, изучает базу, ADR и приступает к реализации фичи. Результатом становится report.md.

Внутри report.md: Что сделано, какие файлы изменены, как это работает, как проверить функционал руками, какие проверки сделаны, были ли отклонения от плана и что Не сделано / риски.

Таким образом, я могу посмотреть, правильную ли логику машина реализовала, какие места пришлось пересмотреть, что может отстрельнуть в будущем и нужно ли это править сейчас. После согласования уже эта модель пишет handoff.mdдля будущего таска.

И так по кругу, пока этап (большая фича) не закончится. После того как этап завершён, начинается фаза рефакторинга.

Рефакторинг у меня означает следующее:

1. Проверить все репорты и планы на соответствие ADR и правдивость (проанализировать код); если есть несостыковки — занести их в later.md

2. Проверить репу линтерами + repowise на предмет кусков кода, которые требуют рефакторинга; если есть — занести в later.md

3. Вынести задачи из later.md в backlog.md и начать их исправлять

Таким образом, получается сохранить документацию актуальной, и я знаю, что когда мне нужно будет полезть в код руками, это не будет страшное и нечитаемое месиво. Раз в несколько этапов я прохожусь по системе руками и вручную тестирую функционал, чтобы убедиться, что все работает корректно.

Учитывая, что задачи на планирование и реализацию разбиты между двумя подписками, за 5-часовой лимит у меня получается закрывать 5–8 задач (например реализация MCP для проекта). При желании и везении в теории можно закрыть один блок задач за 10 часов в два подхода, но я к этому пока не дошел.

Интересно почитать то, как у людей, которые могут запускать рой агентов, устроена работа. Это спеки или что‑то другое? Есть ли ревью планов/репортов или в таких сценариях лучше всего подходит /goal? Поделитесь в комментариях опытом.

P. S. Если будет спрос, то выложу на гитхаб инструкции и описание, которые у меня используются: может, кому‑то это будет полезно.

Источник: habr.com