# claude-harness

Обвязка для разработки с Claude Code: superpowers как процесс, Gitea как память между сессиями, OpenSpec как библиотека спек, codegraph как карта кода, три блокирующих хука как жёсткие правила. Проверена на реальной фиче 27.09.2026 (см. `docs/PILOT-2026-09-27.md`).

## Состав

| Слой | Инструмент | Что помнит | Откуда |
|---|---|---|---|
| Процесс внутри фичи | superpowers ≥ 6.4.1 | ledger плана, рулинги | плагин Claude Code |
| Задачи между сессиями | Gitea issues + PR (`tea`) | что делать, блокеры, human gate на merge | ваш сервер |
| Текущее поведение системы | OpenSpec | требования, дельты, история решений | `npm i -g @fission-ai/openspec` |
| Карта кода | codegraph (MCP) | связи символов для сабагентов | `brew install`/`npm i -g` |
| Контекст по модулям | вложенные CLAUDE.md, ARCHITECTURE.md | границы, конвенции | этот пакет |
| Жёсткие правила | `guard-main.sh`, `require-plan.sh` (PreToolUse) | то, что нельзя доверять промпту | этот пакет |

Что **не** входит и почему: beads (дублирует Gitea), template-bridge (устарел, дублирует ledger), caveman по умолчанию (сжимает отчёты и рулинги; остаётся доступен по `/caveman`).

## Файлы

```
global/CLAUDE.md          глобальные правила процесса → ~/.claude/CLAUDE.md
hooks/guard-main.sh       запрет изменений на main/detached HEAD (Edit/Write/Bash); исключение — коммиты только в openspec/
hooks/require-plan.sh     правки в src/ только при наличии плана или файла .bounded
hooks/settings.hooks.json блок PreToolUse для ~/.claude/settings.json
caveman/config.json       defaultMode: off → ~/.config/caveman/config.json
project-template/         CLAUDE.md, ARCHITECTURE.md, gitignore для нового проекта
examples/                 реальный CLAUDE.md проекта-пилота
install.sh                установка глобальной части, идемпотентно; --check проверяет окружение
new-project.sh            каркас нового проекта: git, CLAUDE.md, openspec init, codegraph init, remote
docs/HARNESS.md           как это работает: слои, цикл фичи, SDD, дисциплина закрытия
docs/PILOT-2026-09-27.md  результаты пилота и находки
```

## Установка

```bash
# 1. Плагины Claude Code (внутри сессии claude)
/plugin install superpowers@claude-plugins-official
/plugin uninstall beads@beads-marketplace            # если стоит
/plugin uninstall template-bridge@template-bridge-marketplace

# 2. CLI
brew install tea && tea login add --name home --url https://<gitea> --token <token>   # scopes: read:user, write:repository, write:issue
npm i -g @fission-ai/openspec
# codegraph: https://github.com/colbymchenry/codegraph

# 3. Глобальная часть
bash install.sh --check
bash install.sh

# 4. Проверка хука: в любом репозитории на main запустить claude и попросить создать файл.
#    Ожидается BLOCKED и предложение создать worktree.
```

## Новый проект

```bash
bash new-project.sh ~/projects/my-app ssh://git@<gitea>:2222/<owner>/my-app.git
```

Заполните `{{...}}` в `CLAUDE.md`, положите фикстуры, запустите `claude` и опишите задачу своими словами. Дальше по `docs/HARNESS.md`.

## Цикл одной фичи, коротко

фраза → агент заводит issue → brainstorming (вопросы, подходы, дизайн) → спека в `openspec/changes/<id>/` + раздел «Decisions made without discussion» → ваше утверждение → план с кодом → ваше утверждение → SDD (контроллер на sonnet, implementer-ы haiku/sonnet, ревью каждой задачи, финальное ревью на opus) → PR в Gitea с рулингами → **вы делаете merge** → «закрывай»: archive, close issue, удаление ветки/worktree/workspace, pull main.

Ручных шагов три: два утверждения и merge. Читать обязательно: спеку один раз, раздел решений каждый раз, когда он пополняется.

## Обновление

`git pull && bash install.sh`. Бэкапы `CLAUDE.md` и `settings.json` создаются автоматически. Раз в два месяца сверяйтесь с `RELEASE-NOTES.md` superpowers: семантика skills между версиями меняется.