К основному содержанию
команда CX Codex

speckit.companion.doctor — команда для Claude Code: как установить

Команда speckit.companion.doctor проверяет здоровье пайплайна спецификаций: находит незавершённые шаги, пропущенные тесты, утечки задач и ложные отметки о дрифте. Работает только на чтение.

MIT ★ 110 обновлён 2026-11-03

Установить в Claude Code · Вручную: положить файлы Все способы и платформы ↓
.claude/commands/speckit.companion.doctor.md
Открыть на GitHub

Что делает speckit.companion.doctor

Команда анализирует прогон спецификации по файлу .spec-context.json и документам фичи. Она пересчитывает дрифт и статус заново, а не доверяет прошлым отметкам. Doctor работает в режиме read-only, ничего не меняет на диске и всегда завершается с кодом 0: если отдельная проверка даёт сбой, утилита помечает её пропущенной и продолжает аудит.

Скрипт выявляет расхождения между статусом и отображением в пайплайне, смешение этапов (например, код реализации внутри tasks.md), шаги без запуска тестов и не созданные артефакты. С флагом --chat инструмент дополнительно разбирает журнал сессии ИИ, находя повторные попытки и лишние перезаписи файлов.

Для работы обязателен Python 3: если python3 не найден в системе, утилита выведет предупреждение и пропустит проверку.

Какие задачи решает

  • найти незавершённые шаги и задачи без записей в журнале
  • пересчитать реальный дрифт кода и выявить ложные отчёты
  • обнаружить этапы реализации, закрытые без запуска проверок
  • проверить сохранность структуры шаблона в tasks.md

Примеры запросов агенту

  • Проверь текущую спецификацию через speckit.companion.doctor
  • Запусти speckit.companion.doctor --all --json
  • Сделай полный аудит сессии: speckit.companion.doctor --feature-dir specs/001-auth --chat

Как установить speckit.companion.doctor

Вручную: положить файлы

.claude/commands/speckit.companion.doctor.md

Вызов — /speckit.companion.doctor. Для всех проектов — ~/.claude/commands/

Вопросы о speckit.companion.doctor

Как установить speckit.companion.doctor в Claude Code?

Размести файл команды по пути .claude/commands/speckit.companion.doctor.md внутри репозитория.

Что делает speckit.companion.doctor?

Команда проводит аудит хода спецификации, находя брошенные шаги, недекларированные правки файлов и расхождения между журналом и интерфейсом.

Что произойдёт, если в системе не установлен Python?

Скрипт требует python3: при его отсутствии утилита выдаёт предупреждение [companion] Warning: python3 not detected; skipped doctor и безопасно пропускает проверку, не прерывая основной процесс.

Исходный текст

speckit.companion.doctor.md · MIT
---
description: "Report on a spec's run health — unfinished steps, unjournaled tasks, step bleed, drift you can judge, a step that closed having verified nothing, a step that closed without the file it promised, and why completion did not land (read-only, retroactive, never halts)"
---

# Pipeline Doctor

Say what actually happened in a run — and where the record, the display, or the run's own claim is at fault. Everything here is **recomputed**, never read off a prior verdict: a run that claimed it was drift-clean gets checked against a fresh drift computation, not believed.

**Read-only.** It creates, modifies, and deletes nothing. **Never halts** — it always exits `0`, and a check that crashes becomes that check's skip reason while the rest still run. **Retroactive** — every core check derives from `.spec-context.json` and the spec's own documents, so it produces a meaningful verdict on a spec created long before this command existed.

## Prerequisites

- Verify Python is available by running `python3 --version`.
- If `python3` is not available, warn the user and skip:
  `[companion] Warning: python3 not detected; skipped doctor`.
  Do not fail the host command.

## Execution

Run the doctor from the repository root. With no argument it examines the active spec, resolved the same way every capture call resolves it:

```bash
python3 .specify/extensions/companion/scripts/doctor.py
```

Name a spec explicitly, or sweep every spec in the repository:

```bash
python3 .specify/extensions/companion/scripts/doctor.py --feature-dir specs/<NNN>-<slug>
python3 .specify/extensions/companion/scripts/doctor.py --all
```

Add `--json` for the machine-readable report (stable top-level keys: `checks`, `findings`, `bleed`, `drift`, `completion`, `chat`), and `--chat` for the deep transcript audit described below.

## What it checks

Each check reports whether it **ran**, was **skipped** (always with a reason), or is **not applicable**. A check that could not look never prints as clean — the summary counts checks, not just findings.

- **record** — steps that started and never finished, tasks checked off in `tasks.md` with no journal entry, task finishes clustered into one burst (journaling that was batched, so the per-task durations mean nothing), and steps closed by the wrong author.
- **triage** — the "status says one thing, the pipeline bar offers another" symptom, resolved into exactly one of two verdicts: *records disagree with each other* (a capture defect — the stepper is derived from `history[]`, so a missing step-level complete is why it will not advance) or *records are consistent* (look at the display).
- **bleed** — where one step did the next step's work: plan content in the spec, a task checklist in the plan, implementation code in the task list, one task list living in two documents, source files committed before implement started, and a pre-implement step that outlasted implement itself.
- **drift** — re-runs the drift computation and shows its work: which capability, which files, which commits. Every flag is classified **real**, **self-inflicted** (the only changes are records the companion writes during a run), **suspect baseline** (the comparison commit is not an ancestor of `HEAD`, or the change is a rename git can follow), or **unknown** (the baseline could not be reached — never reported as clean). A recorded drift-clean claim the recomputation contradicts is reported as a false claim, with both sides and their timestamps.
- **completion** — when a spec did not land as `completed`, which of four things happened: the write was refused (with the writer's own reason), it reported success and never arrived, it landed and the display disagrees, or completion was never attempted at all.
- **verification** — whether the run actually executed anything before implement closed. Running the project's own checks is an instruction with nothing observing it, so a run can write code, tick off a task naming a test, and finish having proven nothing. An implement step that closed with no executed check recorded against the run is reported. A spec that never reached implement reports **no record**, never a problem.
- **artifact** — whether each step left behind the file it declared it would write. Every author node names its output in `writes:`, and the build collects those into a manifest of what a run of this pipeline must produce; a step that quietly stops writing its document otherwise closes exactly like one that wrote it. Reported as a warning, never a gate: the manifest describes the pipeline as built today, and a spec on disk may have been produced by an earlier one. An artifact the size budget is allowed to fold away is not judged, and a step that produced none of what this pipeline declares reports **no record** — it ran some other pipeline.
- **template** — whether `tasks.md` still has the shape it was generated with: user-story phases containing waves, `⟶ Wait` join lines and checkpoints intact. A file whose story sections were renamed or flattened is reported with the offending headings named.
- **built** — whether Companion has caught up with this project's own spec, plan and tasks templates. Spec-kit's override folder and presets reach stock runs at once; Companion follows them from the copy its last pipeline build wrote under `.specify/companion/built/`. A team template with no copy yet, or a copy older than the template it came from, is reported with a note to rebuild. A project with no team template has nothing to judge.
- **agents** — how Spec Kit laid out each agent this project installed (skills or commands, and where), when Companion is installed, any of them missing its commands, which happens because Spec Kit registers an extension for the active integration only, and whether the `specify` CLI is on PATH for headless dispatch and hooks. It is about the project, so a run over many specs reports it once.
- **trace** — what the run self-trace recorded: capture calls that failed and why, call counts, payload sizes, and how many times each file was rewritten. Calls that could not resolve a spec at all land in the repo-level unattributed log and are reported here too, because a spec whose own trace is clean is not evidence that nothing broke while it was being built. The marker naming calls that succeeded but could not be written to the trace is read **before** the check decides a spec has no trace evidence — a run that could not write into its spec directory has no trace file at all, and that is precisely the run with something to report.
- **chat** *(only with `--chat`)* — reads the AI session transcript covering the run's recorded time window and explains causes: work tried and failed, work retried, and steps that stopped rather than failed. It surfaces claims the run made that the recomputation contradicts, and quantifies waste — narration, repeated commands, the same file rewritten over and over. Claude-first; on a provider that keeps no transcript it prints one line and exits successfully. The transcript format is not a stable contract, so treat this as a builder's tool, not a product promise.

## The self-trace

Every capture and drift call records itself to `specs/<NNN>/.trace.jsonl` — one line, success or failure, with the reason verbatim. This costs no extra call and adds nothing to any command body; the scripts the pipeline already runs write it from the inside. The file is size-capped, ignores itself on first write, and is read by nothing but this command. Deleting it is safe; a missing trace is a skipped check, never an error.

## Debug mode

Setting `debug: true` in `.specify/companion.yml` is read by the body renderers, but **the renderers are build-time tools and are not part of a release** — so on an installed project this switch currently does nothing. Treat it as a maintainer tool: from a source checkout, `python3 speckit-extension/scripts/build.py --debug` renders the bodies with per-section timing instrumentation, and a plain rebuild removes it again. Never commit an instrumented body.

To instrument a run on an installed project today, attach the instruction as a node hook in your own `.specify/companion.yml` — that mechanism ships and takes effect on the next dispatched command. See the `debug-timing` hook in this repository's own config for the wording.

## Reporting

Report the doctor's output as it stands. Do **not** fix what it finds as part of running it — the doctor reports, and acting on a finding is a separate, deliberate decision. If it finds nothing, say so along with which checks were skipped and why, so "clean" is never mistaken for "did not look".

© alfredoperez · MIT · alfredoperez/speckit-companion

Похожие слэш-команды

Все слэш-команды по теме «Настройка агента: память, контекст, субагенты» →
dependency-doctor patricio0312rev Скилл dependency-doctor проверяет манифесты проекта, находит устаревшие и дублирующиеся пакеты, уязвимости и рискованные сочетания версий, а на выходе даёт отчёт с планом обновления. CX Codex +1 261установок maintain-verification-skill backnotprop Скилл maintain-verification-skill для Claude Code и Codex: периодически проверяет и корректирует карту фич в проекте через параллельные чтения исходников, сквозное тестирование каждой фичи в живой сессии и одну PR с проверенными правками. CX Codex +1 10 200установок deskstack-doctor Joaquim Тестирует окружение плагина deskstack. Запускается по команде /deskstack-doctor или при ошибках инструментов. CX Codex +1 ★ 86звёзд репо hig-doctor podo Прогоняет HIG Doctor CLI по вашему коду на Swift, React, Flutter или CSS, показывает проблемы с Apple HIG и доступностью по серьёзности и помогает их исправить. CX Codex +1 203установок zoom-integration-doctor официальный Zoom Команда zoom-integration-doctor для Codex проверяет интеграцию с Zoom и расставляет риски по важности. Она запускается для аудита существующего кода до внесения изменений. CX Codex GP ChatGPT +1 ★ 8 052звёзд репо tlc-spec-driven Felipe Rodrigues - github.com/felipfr Скилл tlc-spec-driven для Claude Code организует разработку фич через спецификацию, дизайн, задачи и исполнение. Работа идёт пошагово, с атомарными коммитами и проверкой требований тестами. CX Codex +1 1 300установок

Из того же набора83

Весь набор →
speckit.analyze Слэш-команда speckit.analyze сверяет spec.md, plan.md и tasks.md перед реализацией: ищет расхождения, дубли и требования, под которые не создана ни одна задача. CX Codex GP ChatGPT ★ 110звёзд репо speckit.companion.living-sync Команда speckit.companion.living-sync синхронизирует живые спецификации с текущими правками рабочего дерева в один проход. Обновляет существующие файлы spec без перегенерации. CX Codex +1 ★ 110звёзд репо speckit.implement Промпт speckit.implement читает план разработки и выполняет задачи из tasks.md. Подходит для поэтапной реализации в Claude Code и Codex. CX Codex GP ChatGPT ★ 110звёзд репо publish-all Команда publish-all для Claude Code выпускает четыре компонента проекта, когда изменения готовы и прошли QA. CX Codex +1 ★ 110звёзд репо speckit.plan Субагент speckit.plan проходит этапы планирования по шаблону и создаёт исследовательские и проектные артефакты. Запускайте его после подготовки спецификации функции. CX Codex +1 ★ 110звёзд репо speckit.taskstoissues Субагент speckit.taskstoissues для Claude Code превращает задачи из tasks.md в пронумерованные GitHub-issues, сохраняя порядок зависимостей. Создаёт issues из плана задач. CX Codex +1 ★ 110звёзд репо submit-catalog-update Скилл submit-catalog-update формирует и отправляет issue для обновления расширения companion в каталоге spec-kit. Пригодится мейнтейнерам при выпуске минорных и мажорных версий. CX Codex +1 ★ 110звёзд репо feature-clip Скилл feature-clip ведёт сборку коротких зацикленных роликов SpecKit Companion от захвата в Storybook до файлов для сайта и документации. CX Codex +1 ★ 110звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой