Архитектура

На этой странице описано внутреннее устройство SpecKeep.

Основные Слои

SpecKeep разбит на несколько практических слоев:

• src/cmd/speckeep/ для CLI entrypoint
• src/internal/cli/ для Cobra-команд и пользовательской сборки CLI
• src/internal/project/ для lifecycle-операций workspace, таких как init, обслуживание агентов и cleanup
• src/internal/config/ для загрузки, применения defaults и сохранения .speckeep/speckeep.yaml
• src/internal/templates/ для локализованных generated assets и сборки файлов
• src/internal/agents/ для генерации project-local command или prompt files
• src/internal/specs/ для чтения spec files, используемых публичным CLI
• src/internal/trace/ для чтения записей Proof: из tasks.md
• src/internal/doctor/ для health-check логики

CLI-Слой

Публичный CLI намеренно остается маленьким. В src/internal/cli/ подключаются команды:

• init
• add-agent
• list-agents
• remove-agent
• cleanup-agents
• doctor
• dashboard
• trace
• list-specs
• show-spec

CLI-слой должен оставаться тонким. Основное поведение лучше держать в пакетах project, config, templates, agents и doctor.

Слой Конфигурации

Источник истины для config лежит в .speckeep/speckeep.yaml.

src/internal/config/config.go отвечает за:

• схему config
• применение defaults
• резолв ключевых путей workspace
• загрузку config с диска
• сохранение обновленного config обратно на диск

Это позволяет остальному коду не захардкодить слишком много путей вида .speckeep/....

Слой Templates и Assets

SpecKeep генерирует файлы из локализованных assets, которые лежат в:

• src/internal/templates/assets/lang/en/
• src/internal/templates/assets/lang/ru/

Туда входят:

• constitution.md
• шаблоны spec, plan, tasks и archive
• prompts для constitution, spec, inspect, plan, tasks, implement и verify
• локализованный agents-snippet.md

Общие shell scripts лежат в:

• src/internal/templates/assets/scripts/

Пакет templates собирает эти assets в generated workspace .speckeep/.

Слой Генерации Агентов

src/internal/agents/ генерирует композитный skill-pack для каждого поддерживаемого target:

• claude, codex, copilot, cursor, kilocode
• opencode, trae, windsurf, roocode, aider
• amazonq, gemini, jules, cline, continue
• devin, goose, refact, codiumate, qwen-code

Все target'ы используют один рендерер (skill_pack.go): лёгкий обзорный sdd/SKILL.md (progressive-disclosure точка входа для неоднозначных запросов) плюс по одному независимому, напрямую слэш-вызываемому скиллу spk-<фаза>/SKILL.md на каждую фазу, раскладывается в skills-директорию каждого таргета (targetSkillDirs). Генерация per-command обёрток и пользовательский skills-менеджмент удалены; каждый фазовый скилл инлайнит тело канонического промпта из .speckeep/templates/prompts/ в момент рендера (через templates.PromptContent), так что агент читает полные инструкции фазы из одного файла вместо перехода по указателю, а файл промпта остаётся единственным authored source. Детерминированный CLI (check/guard/converge) — проверяющий остов, который скиллы зовут как гейты.

Фазовые скиллы — независимые top-level директории (spk-spec/SKILL.md, spk-plan/SKILL.md, ...), а не вложенные файлы-ресурсы под одним композитным скиллом (sdd/phases/*.md), потому что загрузчики skills вроде Claude Code слэш-вызывают только top-level <dir>/SKILL.md — вложенный файл достижим лишь когда модель сама решает его открыть, никогда — набором команды пользователем. agents.LegacySkillPhasePaths покрывает очистку старого вложенного layout для любого workspace, обновлённого до этого изменения.

Так сохраняется один главный источник истины для workflow prompts при поддержке нескольких агентных экосистем.

Слой Жизненного Цикла Проекта

src/internal/project/init.go управляет lifecycle workspace:

• инициализация проекта
• добавление agent targets
• получение списка agent targets
• удаление agent targets
• очистка orphaned agent artifacts
• создание вспомогательных скриптов в .speckeep/scripts/

Этот слой отвечает за:

• создание layout .speckeep/
• запись generated files
• обновление AGENTS.md
• синхронизацию enabled agent targets в config

Слой Прослеживаемости и Верификации

Пакет src/internal/trace/ реализует основную логику связи доказательств реализации с требованиями:

• читает записи Proof: из tasks.md
• фильтрует находки по слагу фичи
• поддерживает JSON-вывод для интеграции с workflow верификации

Этот слой позволяет фазе verify оставаться экономной по токенам, заменяя ручной анализ кода детерминированным чтением записей Proof: из tasks.md.

Слой Здоровья и Обслуживания

src/internal/doctor/doctor.go и src/internal/gitutil/ проверяют здоровье и согласованность workspace.

Он валидирует:

• наличие обязательных директорий и файлов
• корректность настроенных языков
• наличие generated files для включенных agent targets
• отсутствие незамеченных stale artifacts от отключенных targets
• Smart Branching: проверяет соответствие текущей ветки Git слагу фичи (ожидается feature/<slug>)
• Traceability Integrity: предупреждает об осиротевших/дублирующихся/отсутствующих записях Proof: или невалидных ссылках на AC-*

Связанные maintenance-команды:

• remove-agent отключает target и удаляет его generated files
• cleanup-agents удаляет orphaned leftovers для отключенных targets
• doctor сообщает error, warning и ok
• dashboard предоставляет визуальную сводку прогресса, статуса и здоровья веток проекта

Принципы Дизайна

Внутренняя архитектура следует нескольким важным принципам:

• держать публичный CLI маленьким
• делать generated assets language-aware, но структурно согласованными
• выносить readiness checks в shell scripts, когда это возможно
• держать один канонический источник prompt-логики вместо дублирования
• сохранять strict workflow phases без тяжелого orchestration engine
• экономить токены через контроль read sets и scope артефактов

Anti-Bloat Checklist

Используйте этот checklist перед добавлением новой фичи, prompt-правила, скрипта или артефакта:

• Увеличивает ли это default read set? Если да, по умолчанию это риск.
• Можно ли решить задачу дешевым deterministic helper вместо дополнительного reasoning?
• Делает ли это новый артефакт обязательным для каждой фичи? Если да, стоит пересмотреть решение.
• Требует ли это чтения implementation code по умолчанию? Если да, решение, скорее всего, слишком тяжелое.
• Можно ли начинать workflow от constitution, spec, plan или tasks до чтения кода?
• Расширяет ли это публичный CLI без явной пользы для повседневной работы?
• Добавляет ли это совершенно новый gate, или можно усилить уже существующую фазу?
• Можно ли объяснить ценность изменения одним коротким предложением? Если нет, есть риск лишней процессной сложности.
• Приближает ли это SpecKeep к бюрократии в стиле spec-kit без сопоставимой пользы?
• Улучшает ли это brownfield ergonomics на практике?

Изменение обычно хорошо вписывается в SpecKeep, если выполняет хотя бы одно из двух:

• повышает качество без расширения default context
• заменяет дорогой reasoning дешевой структурной проверкой