Написание машиночитаемых спецификаций в Markdown

Чем меньше времени вы тратите на написание кода вручную, тем быстрее и качественнее Claude Code создаст для вас сложную систему. Это кажется парадоксальным: мы привыкли думать, что программирование — это процесс написания строк кода. Однако в мире «вайбкодинга» программирование — это проектирование логики, а написание кода — лишь побочный эффект хорошо составленной спецификации.

Проблема: Почему ИИ «галлюцинирует»?

Представьте, что вы просите строителя «построить уютную кофейню». Без чертежа один строитель сделает стены из дерева, другой — из бетона, а третий забудет про туалет. Claude Code работает так же. Если вы дадите ему расплывчатое описание текстом, он начнет заполнять пробелы в логике на свое усмотрение. Это приводит к ошибкам, которые потом приходится исправлять часами. Проблема не в интеллекте ИИ, а в отсутствии четкого фундамента, на который он мог бы опереться.

Концепт: Архитектура как Единый источник истины

Методология Spec-First (Сначала спецификация) утверждает: прежде чем появится первая строчка кода, должна появиться полная техническая опись системы. В центре этой методологии стоит паттерн Architecture.md. Это не просто текстовый файл, а Единый источник истины (SSOT).

SSOT означает, что если в системе что-то меняется, это сначала меняется в Architecture.md. Claude Code всегда обращается к этому файлу, чтобы понять: какие данные мы собираем, как они связаны и какие правила нельзя нарушать. Чтобы ИИ понимал нас идеально, мы используем Машиночитаемую структуру Markdown. Это использование заголовков, списков и таблиц не для красоты, а для создания иерархии смыслов, которую алгоритмы парсинга ИИ считывают мгновенно.

Минимальный рабочий пример: Architecture.md

Ниже представлен скелет файла Architecture.md для системы анализа отзывов в кофейнях. Этот файл — «мозг» вашего проекта.

# Feedback System: Coffee Chain
## 1. System Overview<!-- Краткое описание: что делает система и зачем -->Автоматизированный сбор и классификация отзывов клиентов.
## 2. Data Models| Field | Type | Description || :--- | :--- | :--- || review_id | UUID | Уникальный идентификатор отзыва || sentiment | Enum | POSITIVE, NEGATIVE, NEUTRAL || branch_id | String | ID кофейни, где был оставлен отзыв |
## 3. Business Rules- Все отзывы с оценкой 1 или 2 звезды должны помечаться как `CRITICAL`.- Ответ на критический отзыв должен быть отправлен в течение 2 часов.

Разбор примера

Почему мы написали именно так?

1. Заголовки (#, ##): Claude Code использует их как навигационные маркеры. Он понимает, что все, что находится под заголовком Data Models, относится к структуре данных.
2. Таблицы: Это самый быстрый способ задать типы данных. Когда ИИ видит UUID или Enum, он перестает гадать и использует конкретные программные типы.
3. Бизнес-правила: Это «законы» вашей системы. Если они прописаны в Architecture.md, Claude Code не предложит решение, которое их нарушает.

Расширенный пример: Логика взаимодействия

В реальной системе нам нужно описать не только данные, но и то, как они движутся. Мы добавим раздел Logic Flow, чтобы Claude Code знал последовательность действий.

Распространенные ошибки

1. Смешивание спецификации и инструкций: В Architecture.md мы пишем что это за система, а не как Claude Code должен её писать в данный момент. Инструкции по написанию («Создай файл X») — это для чата, а архитектура — это вечный документ.
2. Избыточность текста: Избегайте вежливых слов и длинных вступлений. «Пожалуйста, создай базу данных, которая была бы очень удобной» — это плохо. «DB: PostgreSQL, Schema: Public» — это хорошо.
3. Нарушение SSOT: Если вы изменили структуру базы в коде через Claude Code, но не обновили Architecture.md, при следующем запросе ИИ вернется к старой версии из документа и «сломает» ваш новый код.

Реальное применение: Масштабирование

Когда сеть кофеен вырастет с одной точки до 100, ваша спецификация Architecture.md станет фундаментом для внедрения ИИ-аналитиков. Имея четкую структуру данных (SSOT), вы сможете добавить модуль «Предсказание спроса» просто дописав новый раздел в спецификацию. Claude Code прочитает существующую структуру, увидит новые требования и интегрирует их, не нарушив логику работы старых кофеен. Без Architecture.md такая интеграция превратилась бы в бесконечную цепочку багов.