Конвейер агентной разработки: определения агентов и команд в .claude/ - #18
Open
iljyxa wants to merge 4 commits into
Open
Конвейер агентной разработки: определения агентов и команд в .claude/#18iljyxa wants to merge 4 commits into
iljyxa wants to merge 4 commits into
Conversation
CLAUDE.md и docs/agentic-pipeline.md описывают TDD-конвейер из шести субагентов и ссылаются на их определения в .claude/agents/*.md, но каталог .claude целиком игнорировался git (коммит 06ae514) — файлы физически не существовали, документация описывала процесс, который нельзя выполнить. - .gitignore: вместо исключения всего каталога игнорируется только личный .claude/settings.local.json — конвенция инструмента: агенты, команды и общие настройки коммитятся и шарятся с командой. - .claude/agents/: шесть субагентов по таблице ролей из docs/agentic-pipeline.md (architect, test-writer, developer, qa-e2e, reviewer, documenter). Модель и набор инструментов соответствуют таблице; architect и reviewer read-only. Каждый ссылается на CLAUDE.md и профильные docs/, не дублируя их. - .claude/commands/: семь команд — /pipeline (основной вход, триаж FAST/FULL), /triage, /qa, /review, /document, /sanity, /commit. /pipeline и /commit запускаются только человеком (disable-model-invocation) — первая разворачивает шесть агентов, вторая коммитит. - .claude/hooks/restrict-write-paths.mjs: PreToolUse-хук, ограничивающий test-writer и documenter записью только в их каталоги (src/test и docs/CLAUDE.md/README.md соответственно) — поле tools: умеет только выдать или отнять инструмент целиком, path-ограничения только через хук. - .claude/settings.json: разрешения под реальные команды конвейера, включая MOCHA_GREP=* npm run test:fast и VSCODE_TEST_VERSION=* npm test — правило npm run * их не покрывает, т.к. allow-правило не матчится сквозь присваивание переменной окружения вне известного безопасного набора. git commit/push не разрешены — требуют явного подтверждения. - scripts/cloud-setup.sh: подготовка headless-окружения (Claude Code Cloud, CI). npm test поднимает настоящий VS Code на Electron через @vscode/test-electron — без виртуального X-дисплея не стартует; скрипт ставит xvfb и прогревает сборку. - docs/agentic-pipeline.md, CLAUDE.md: исключение для нерантайм-изменений — если задача не трогает src/**, src-ui/**, src/test/**, qa-e2e не гоняет полный npm test/coverage:changed, только проверяет структуру/конфигурацию. reviewer выполняется в любом случае. - README.md: раздел для разработчиков — раскладка .claude/, таблица команд, разрешения, ограничение агентов по путям, настройка Claude Code Cloud.
…hook Ошибка "bash: ./scripts/cloud-setup.sh: No such file or directory" (exit 127) из поля Setup script — не проблема ветки или прав файла (проверено: 100755, верный шебанг, LF, файл в дереве коммита). Причина в порядке инициализации: Setup script выполняется ДО запуска Claude Code, когда рабочая директория не гарантированно совпадает с клоном репозитория — документация даёт такую гарантию только для хуков, через $CLAUDE_PROJECT_DIR, специально потому что для них CWD сессии тоже не гарантирован. - scripts/cloud-setup.sh: сужен до проектной части (npm ci + прогрев сборки), гейт по CLAUDE_CODE_REMOTE=true — хук срабатывает и локально, гейт не даёт ему мешать npm run watch на своей машине. - .claude/settings.json: SessionStart-хук вызывает скрипт через "$CLAUDE_PROJECT_DIR"/scripts/cloud-setup.sh — задокументированный способ надёжно сослаться на файл репозитория из настройки окружения. - README.md: системная часть (xvfb, библиотеки Electron) — инлайн-текстом прямо в поле Setup script UI облака, без обращения к файлам проекта; разделение объяснено и обосновано документацией Claude Code Cloud.
…ючённой песочницы
Агенты конвейера не могли запустить npm test/npm run test:fast со стандартными
настройками Bash — Electron-хост (@vscode/test-electron) убивается сигналом
под песочницей. Нигде в .claude/agents/*.md, .claude/settings.json и
docs/agentic-pipeline.md это не было описано, поэтому каждый агент открывал
ограничение заново и тратил проход на диагностику уже известной проблемы —
вместо живого прогона test-writer подменял его статической проверкой
(tsc --noEmit) или объявлял тест непроверяемым.
- .claude/settings.json: sandbox.excludedCommands — npm test и
npm run test:fast (с формами под MOCHA_GREP/VSCODE_TEST_VERSION) всегда
выполняются вне песочницы.
- .claude/agents/{test-writer,developer,qa-e2e}.md: строка в разделе команд —
тестовые команды идут с отключённой песочницей, compile/lint/test:compile/
coverage:* обычным способом.
- docs/agentic-pipeline.md: то же самое рядом с описанием быстрого цикла
test:compile → MOCHA_GREP=… test:fast.
Заодно зафиксирован унаследованный красный на фикстурах example/ (каталог в
.gitignore, у каждого своя копия) — известное состояние окружения, не
регресс задачи; агенты стабильно путали расхождение локальной фикстуры с
поломкой своего изменения.
… developer documenter не трогает src/** (промпт + хук restrict-write-paths.mjs), но комментарии в коде протухают от тех же рефакторингов, что и docs/, — и ловить это должен именно documenter. На практике reviewer нашёл четыре устаревшие ссылки на перенесённые/переименованные функции в RepositoryFileSyncRunner.ts, RepositoryService.ts, RepositoryCommandRunner.ts и repositoryService.test.ts; documenter подтвердил находки, но исправить не смог и вернул оркестратору без результата — правки в итоге сделал оркестратор вручную, уже в самом конце прогона, не как штатный шаг. - .claude/agents/documenter.md: новая обязанность — искать и ПЕРЕЧИСЛЯТЬ протухшие комментарии в затронутом src/** отдельным разделом отчёта (файл:строка → что устарело → чем заменить), не пытаясь их починить — хук всё равно откажет. Расширение прав не рассматривалось: documenter на более простой модели, отличить «правку комментария» от «заодно правки кода» хук не умеет, а снятие ограничения открывает весь src/**. - docs/agentic-pipeline.md, шаг 6 TDD-петли: непустой список — обязательный микро-возврат оркестратору/developer ДО завершения задачи, а не сюрприз, всплывающий в самом конце. Пустой список — стадия закрыта без возврата.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Проблема
CLAUDE.mdиdocs/agentic-pipeline.mdописывают TDD-конвейер из шести субагентов и ссылаются наих определения в
.claude/agents/*.md. Этих файлов в репозитории нет: каталог.claudeцеликомпопал в
.gitignore(коммит 06ae514), поэтому всё, что там создаётся, git не отслеживает.Следствие — документация описывает процесс, который нельзя выполнить. Запуск стадии вида
architectзавершается ошибкой «нет такого типа агента», и конвейер либо молча вырождается вработу одним чатом, либо теряет разделение прав между ролями (
architect/reviewerподокументации read-only, но универсальный агент получает все инструменты).
Что сделано
.gitignore— вместо исключения всего каталога игнорируется только личный.claude/settings.local.json. Остальное в.claude/по конвенции инструмента общее: агенты,команды и общие настройки шарятся с командой и работают в чистом клоне.
.claude/agents/— шесть субагентов ровно по таблице ролей изdocs/agentic-pipeline.md:architect,test-writer,developer,qa-e2e,reviewer,documenter. Модель и наборинструментов у каждого соответствуют колонкам таблицы;
architectиreviewerread-only —у них нет
Edit/Write. Единый источник правды не дублируется: агенты ссылаются наCLAUDE.mdи профильные
docs/, как того требует сам документ..claude/commands/— семь команд:/pipeline(основной вход с триажем FAST/FULL),/triage,/qa,/review,/document,/sanity(механические проверки из «Sanity-чек после изменений»),/commit(коммит по правилам проекта: явные файлы, русское сообщение, без пуша)./pipelineи/commitзапускаются только человеком — первая разворачивает шесть агентов,вторая имеет побочный эффект. У
/commitallowed-toolsсужен до конкретных git-команд, а неголого
Bash, чтобы пред-одобрение инструментов не распространялось наgit push, который самакоманда запрещает.
.claude/hooks/restrict-write-paths.mjs— ограничение агентов по путям. Настройка инструментовумеет только выдать или отнять инструмент целиком, поэтому правила «
test-writerправит толькотесты» и «
documenterправит только документацию» до сих пор держались на тексте промпта. Хукотклоняет запись за пределами разрешённых каталогов. Написан на Node, а не на bash, ради Windows.
.claude/settings.json— общие разрешения под команды, которые конвейер выполняет постоянно.Отдельными правилами добавлены
MOCHA_GREP=* npm run test:fastиVSCODE_TEST_VERSION=* npm test:общее правило
npm run *их не покрывает, поскольку разрешение не сопоставляется сквозьприсваивание переменной окружения вне известного безопасного набора.
git commitиgit pushв список сознательно не включены.
scripts/cloud-setup.sh+ SessionStart-хук — подготовка headless-окружения (Claude Code Cloud,CI).
npm testподнимает настоящий VS Code на Electron через@vscode/test-electronи безвиртуального X-дисплея не стартует. Подготовка разнесена на два места по границе, которую задаёт
сама модель Claude Code Cloud:
xvfbи библиотеки Electron) — инлайн-текстом в поле Setup script UIоблака (см.
README.md), т.к. на этом этапе нет гарантии, что рабочая директория совпадает склоном репозитория;
npm ci+ прогрев сборки) — вscripts/cloud-setup.sh, вызывается черезSessionStart-хук (
.claude/settings.json) с обращением"$CLAUDE_PROJECT_DIR"/scripts/cloud-setup.sh— единственный задокументированный способ надёжно сослаться на файл репозитория из настройки
окружения. Хук гейтится по
CLAUDE_CODE_REMOTE=true, чтобы не мешатьnpm run watchлокально.docs/agentic-pipeline.mdиCLAUDE.md— зафиксировано исключение для нерантайм-изменений:если задача не трогает
src/**,src-ui/**,src/test/**, стадияqa-e2eне гоняет полныйnpm test/coverage:changed, а ограничивается проверкой структуры и конфигурации.reviewerвыполняется в любом случае. Формулировка синхронизирована в обоих документах.
README.md— раздел для разработчиков: раскладка.claude/, таблица команд с областьюприменения, разделение личных и общих настроек, разбор разрешений, настройка облачного окружения
с точным содержимым поля Setup script.
Важно: PR удаляет
.claude/settings.local.jsonФайл сейчас отслеживается git, хотя по конвенции инструмента это личные настройки конкретного
разработчика (в текущей версии там путь
c:\Projects\v8vscedit, то есть настройки одной машины,применяемые ко всем). После вливания он перестаёт отслеживаться и подпадает под
.gitignore.Практическое следствие: при переключении на эту ветку файл исчезнет из рабочего дерева — git
не различает «удалить» и «перестать отслеживать», на уровне коммита это одна операция. Всё, что
нужно для работы конвейера, перенесено в общий
.claude/settings.json, так что восстанавливатьспециально ничего не требуется. Если в личном файле были свои предпочтения (например
outputStyle)— достаточно создать его заново, теперь он корректно игнорируется.
Если локальная копия была изменена, git не удалит её молча: переключение веток прервётся с
предупреждением или создаст modify/delete-конфликт.
Влияние на сборку и тесты
Изменения полностью нерантайм: ни строки в
src/**иsrc-ui/**. Затронуты только конфигурацияинструментария, документация и новый скрипт подготовки окружения. Сборка, тесты и покрытие не
затрагиваются.
Как проверить
/pipeline,/triage,/sanityи остальные команды доступны без ручнойнастройки.
/sanityпрогоняетnpm run compile,npm run lintи rg-проверки архитектурных инвариантов изCLAUDE.md.README.md(раздел «Claude CodeCloud»); проектная часть подхватывается автоматически через SessionStart-хук.