claude-code-starter

Claude Code Starter v6

Claude Code Starter — это готовая управляющая среда для проектов, в которых основной рабочий агент — Claude Code.

Он нужен не для генерации приложения, а для того, чтобы быстро добавить в любой проект:

• понятный CLAUDE.md вместо мегадокумента;
• модульные rules, skills, agents, hooks;
• двух-осевую проектную память — контракты (ARCHITECTURE.md, INVARIANTS.md, methodology/) и state (SNAPSHOT.md, BACKLOG.md, dialogs/);
• methodology layer с лестницей зрелости (draft → pattern → mature → crystallized) для пайплайнов с автоматическими LLM-вызовами;
• dialog preservation — JSONL текущей сессии сохраняется в .claude/dialogs/ до того, как Claude Code сделает retention cleanup;
• оркестраторскую модель работы — владелец остаётся продуктом над производством, агент сам поднимает и координирует воркеров;
• единый installer для нового, существующего и legacy-проекта;
• явный контроль над тем, что framework state делает с git-историей.

Новое в v6.3.0: фреймворк переходит на оркестраторскую модель. Владелец — продукт/методолог над производством: даёт цель, границы полномочий, ревьюит результат и решает на стоп-точках. Агент — оркестратор и главный девелопер: сам режет работу на потоки, сам поднимает воркеров (субагенты / изолированные worktree / детерминированные workflows), интегрирует, независимо верифицирует и коммитит — не дёргая владельца на подтверждение каждого шага. Handoff эволюционирует из ручного «моста», который владелец переносил между сессиями, во внутренний charter, который оркестратор выдаёт воркерам; непрерывность контекста между сессиями держит ограниченная двух-осевая память + тонкий указатель, а не разрастающийся мегафайл. Модель поставляется как переносимый свод правил orchestration-model.md (принципы O1–O12), правила autonomy/delegation эволюционированы под неё, скилл /handoff теперь входит в поставку. См. release-notes/v6.3.0.md.

Новое в v6.2.1: /start skill переписан — убран кэп «доложи 3-5 строк» (он читался моделью как потолок глубины, а не пол краткости), добавлен обязательный шаг заземления карты в территорию (git log + wc + grep против заявлений метафайлов), пометка «карта ≠ территория». В шапке CLAUDE.md — новая секция «Назначение этого файла» с тремя видами ограничений (действия / внимание / глубина): первые два — нормальны, кэп на глубину — структурный баг. В validate-release.sh — запрет на параллельный ONBOARDING.md (конституция только в CLAUDE.md). См. release-notes/v6.2.1.md.

Новое в v6.2.0: восстановлены слои памяти ARCHITECTURE.md и BACKLOG.md, добавлены INVARIANTS.md и каталог methodology/ с лестницей зрелости (draft → pattern → mature → crystallized). Добавлен механизм dialog preservation (scripts/save-dialogs.sh, skill /save-dialog, авто-сохранение при /finish).

Новое в v6.0–6.1: автоматическое определение типа проекта (code / content / hybrid). Контентные проекты — книги, курсы, базы знаний, документы, транскрипты — получают свой набор правил, навыков и агентов (writer, editor, content-reviewer). Опциональный глобальный слой ~/.claude/ с /setup-project skill. Установка без флагов: bash init-project.sh сам поймёт, где находится, и поставит подходящий слой.

Зачем Это Нужно

Обычно при работе с агентом проект быстро расползается:

• инструкции живут в одном длинном CLAUDE.md;
• правила смешаны с контекстом проекта;
• старт нового проекта и миграция старого проекта делаются по-разному;
• агентная память теряется между сессиями;
• внутренние framework-файлы случайно попадают в shared/public git history.

Claude Code Starter решает эти проблемы:

• отделяет проектный паспорт от operational logic;
• даёт стандартную структуру .claude/;
• добавляет reusable workflows через skills;
• добавляет background guardrails через hooks;
• поддерживает single-file installation;
• вводит repo_access, чтобы память агента не утекала туда, где ей не место.

Что Устанавливается В Проект

После установки в хост-проекте появляется такая база:

.claude/
  rules/                # операционные правила (autonomy, delegation, dialog-preservation, ...)
                        #   autonomy + delegation несут оркестраторскую модель (v6.3.0+):
                        #   владелец над производством, агент сам поднимает воркеров
  skills/               # /start, /finish, /save-dialog, /testing, ...
  agents/               # researcher, implementer, reviewer (+ writer/editor для content)
  hooks/                # фоновые guardrails (pre-compact, post-compact, ...)
  logs/                 # сессии, миграции, ошибки (gitignored)
  dialogs/              # архив JSONL сессий (по умолчанию gitignored)
  SNAPSHOT.md           # state: текущая точка работы
  BACKLOG.md            # state: Next / Soon / Later / Won't do
  ARCHITECTURE.md       # contract: карта системы
  INVARIANTS.md         # contract: жёсткие правила, нарушение = баг
  settings.json
methodology/            # contract: методологии для пайплайнов
  _HOW-THIS-GROWS.md
  templates/            # draft / pattern / mature / crystallized
  draft/ patterns/ mature/
  00-example-llm-as-component.md
scripts/
  framework-state-mode.sh
  switch-repo-access.sh
  save-dialogs.sh
CLAUDE.md
manifest.md
.gitignore

Двух-осевая память (см. CLAUDE.md секция «Слои памяти»):

• Контракты — что должно быть (медленно меняется): ARCHITECTURE.md, INVARIANTS.md, methodology/
• State — что есть сейчас (быстро меняется): SNAPSHOT.md, BACKLOG.md, dialogs/

Ключевые файлы:

• CLAUDE.md — паспорт проекта;
• manifest.md — project_name, repo_access, project_type, content_type;
• .claude/SNAPSHOT.md — что в работе прямо сейчас;
• .claude/BACKLOG.md — план: Next / Soon / Later / Won't do;
• .claude/ARCHITECTURE.md — карта модулей, контрактов, зависимостей;
• .claude/INVARIANTS.md — правила, нарушение которых — баг, не предпочтение;
• .claude/dialogs/ — архив сессионных JSONL для последующего анализа;
• methodology/ — методологии с лестницей зрелости (draft → pattern → mature → crystallized);
• .claude/rules/, .claude/skills/, .claude/agents/, .claude/hooks/ — operational слой;
• scripts/save-dialogs.sh — идемпотентное сохранение JSONL сессии;
• scripts/switch-repo-access.sh — безопасное переключение между private-solo, private-shared, public.

Требования

Обязательно:

• bash
• git
• Claude Code с поддержкой:
  • .claude/rules/
  • .claude/skills/
  • .claude/agents/
  • .claude/hooks/

Рекомендуется:

• python3

Опционально:

• node / npm
• pytest
• sqlite3
• psql
• supabase

python3 нужен не для bootstrap, а для безопасного merge settings.json в migration flow.

Установка

Вариант 1. Один файл

Возьми root installer init-project.sh, положи его в корень целевого проекта и запусти:

chmod +x init-project.sh
./init-project.sh

Никаких флагов не нужно. Launcher сам определит:

Сценарий установки:

• new — новый проект;
• existing — существующий без framework;
• legacy — старый framework;
• upgrade — частично установленный.

Тип проекта (по содержимому файлов и папок):

• code — обычный software-проект;
• content — книги, курсы, KB, документы, транскрипты;
• hybrid — и код, и контент.

Тип контента для контентных проектов:

• book — папки chapters/, briefs/, bible/;
• course — папки modules/, lessons/;
• knowledge-base — articles/, INDEX.md;
• documents — docs/;
• transcripts — Section-*/, *-Lecture-*;
• mixed — несколько сразу.

Если установка затрагивает существующий CLAUDE.md, он мержится аддитивно через scripts/lib/merge_claude_md.py — кастомные секции пользователя сохраняются, фреймворк добавляет только недостающее. При жёстком конфликте установка останавливается и в .claude/CLAUDE.md.merge-proposal.md пишется конкретное предложение разрешения.

Вариант 2. Из локального checkout

cd /path/to/your/project
bash /absolute/path/to/claude-code-starter/init-project.sh

Вариант 3. Глобальный слой + skill /setup-project

Если хочешь, чтобы framework был доступен в любой папке без скачивания каждый раз — поставь его в ~/.claude/:

bash /path/to/claude-code-starter/scripts/install-global.sh

Это аддитивно копирует rules / skills / agents в ~/.claude/, не трогая существующие настройки. Делает backup в ~/.claude/.backup-TIMESTAMP/. После этого:

mkdir my-new-project && cd my-new-project
# Открой Claude Code в этой папке и скажи:
# /setup-project   — или просто: «новый проект» / «поставь фреймворк»

Skill /setup-project сам найдёт checkout, определит тип проекта и поставит framework. Никакой ручной загрузки init-project.sh не требуется.

Откат: bash scripts/install-global.sh --rollback.

Полезные параметры

./init-project.sh --name "My Project"
./init-project.sh --type content --content-type book
./init-project.sh --mode init
./init-project.sh --mode migrate
./init-project.sh --template /path/to/local/framework
./init-project.sh --rollback
./init-project.sh --apply-proposal
./init-project.sh --force

Поддерживаются:

• --name — имя проекта для свежего bootstrap;
• --type code|content|hybrid|auto — override автодетекта типа проекта;
• --content-type book|course|knowledge-base|documents|transcripts|mixed — override автодетекта типа контента;
• --mode init — принудительный bootstrap;
• --mode migrate — принудительная migration/integration;
• --template — использовать локальный checkout framework вместо download;
• --rollback — восстановить файлы из последнего .claude/backup-*/ snapshot;
• --apply-proposal — применить предложение из .claude/CLAUDE.md.merge-proposal.md;
• --force — перезаписать существующие файлы (для разработчиков фреймворка).

Что Делать После Установки

1. Заполнить CLAUDE.md под конкретный проект.
2. Проверить manifest.md.
3. Если проект shared/public, переключить режим до первого framework commit:

scripts/switch-repo-access.sh public --commit

или

scripts/switch-repo-access.sh private-shared --commit

4. Открыть проект в Claude Code и запустить /start.

Repo Access

repo_access задаётся в manifest.md.

Режимы:

• private-solo — framework files можно хранить в git;
• private-shared — framework files должны оставаться локальными;
• public — framework files должны оставаться локальными.

Практический смысл:

• если репозиторий личный, можно хранить framework state в истории;
• если репозиторий общий или публичный, память агента не должна попадать в branch history.

Если framework state уже успел попасть в remote history, одного .gitignore недостаточно. Для таких случаев и существует scripts/switch-repo-access.sh.

Как Устроен Этот Репозиторий

Публичный вход:

• init-project.sh — единственный installer entrypoint

Внутренний payload:

• scripts/init-project.sh — bootstrap payload