project-architect

Imported from pete-doc/project-architect (AGENTS.md). Install upstream with npx skills add pete-doc/project-architect. Copyright stays with the author.

AGENTS.md — ProjectArchitect

Набор инструментов (плагин Claude Code + шаблоны), который держит ИИ-разработку под контролем. Полное ТЗ — BUILD_PLAN.md. Работаем по одной фазе за сессию.

Структура

• plugin/ — плагин Claude Code (имя parch): agents/, hooks/, skills/, манифест в plugin/.claude-plugin/plugin.json.
• .claude-plugin/marketplace.json — каталог для установки плагина.
• plugin/templates/ — шаблоны для целевых проектов (внутри плагина, иначе они не попадают в установку): docs/, ci/, state/, claude/ (правила permissions).
• tests/ — тесты продукта, включая «плохие примеры».
• docs/adr/ — решения по самому продукту.

Как собирать и проверять

Нужен Python 3.12+ и Node (для pyright). Из корня репозитория:

pip install -r requirements-dev.txt
python scripts/preflight.py

scripts/preflight.py — единая команда «проверить перед отправкой»: ruff, формат, pyright, standard, полный прогон тестов; останавливается на первой ошибке. Если PR меняет только текст, идёт один standard. С флагом --update-baseline после чистого прогона обновляет baseline (отчёт test-report.xml остаётся в корне).

Тесты идут параллельно (pytest-xdist, -n auto) в двух режимах:

Маркер slow получает каждый тест, который запускает dotnet, pwsh, node или PSScriptAnalyzer (по фикстурам автоматически, остальные помечены вручную). Для полного режима нужны .NET SDK точной версии из tests/projects/cs_shop/global.json, PowerShell 7 (pwsh) с PSScriptAnalyzer 1.25.0 (Install-Module PSScriptAnalyzer -RequiredVersion 1.25.0 -Scope CurrentUser) и Node; в CI всё это ставится. Если полный прогон падает из-за памяти (Array buffer allocation failed), не обходи это переключателями: напиши владельцу.

Проверка манифестов плагина (нужен установленный Claude Code):

claude plugin validate ./plugin
claude plugin validate .

Перед каждой отправкой (ADR-0013)

CI подтверждает, он не отлаживает. Красный прогон «на проверку» запрещён: каждая отправка в PR должна пройти локально всё, что проверит CI. Проверки соразмерны изменению:

• Правки только текста (AGENTS.md, CLAUDE.md, docs/**/*.md, ADR, BACKLOG, отчёты в state/incidents/, state/acceptance/; исключения: docs/GOAL.md, docs/MODULES.md, docs/CONSTITUTION.md, docs/STANDARD.md, CONSTITUTION.md, всё остальное в state/, включая baseline.json и features.json): тесты не нужны, локально и в CI идёт только standard. Тесты не проверяют смысл текста; для защищённых текстовых файлов проверка это «сливай» владельца. Если правился ADR, обнови индекс (/parch:adr index) вручную.
• Мелкие правки текста отдельным PR не оформляй: добавляй в ближайший PR по делу или копи вместе.
• Всё остальное (код, тесты, шаблоны, .github/, файлы правил проверок) идёт по шагам ниже.

1. Запусти python scripts/preflight.py (ruff, формат, pyright, standard, полный прогон pytest -m ""). Не прошло локально, не отправляй. Заметил повторную ошибку процесса: внеси её в docs/LESSONS.md, на втором повторе нужна автоматика, а не напоминание.

2. Обнови baseline локально до отправки (если тесты добавлены, удалены или переименованы) и закоммить вместе с тестами:

   python plugin/templates/ci/parch/parch_ci.py baseline --update --only-tests --report-platform windows --report test-report.xml

   Отчёт снят на Windows, поэтому --report-platform windows: пропуски, которые бывают только на Linux (тесты запуска hooks через cmd), остаются в списке для posix. На macOS и Linux указывай posix. Удаление или переименование теста (--accept-removed) и пропуск теста (--accept-skips) возможны только с решением владельца.

3. Если CI всё-таки упал, это значит, что проверка не была сделана локально: найди, какую, исправь и воспроизведи локально до новой отправки. Новая отправка «посмотреть, что скажет CI» запрещена.

CI и слияние (ADR-0013)

CI идёт на Ubuntu; тесты hooks и запускающего файла дополнительно на Windows (job windows-hooks, только если PR меняет hooks, шаблоны или .github). Он разделён на две части:

• Быстрая часть (ci.yml, job check) на каждую отправку: проверки, быстрые тесты, медленные тесты только тех языков, чьи файлы изменил PR (.github/scope.py). Её отчёт помечен как урезанный (parch-partial), права на слияние она не даёт. PR только с текстом (список выше) идёт без тестов, в CI только standard; всё остальное в docs/ и state/ (включая state/baseline.json и любые файлы правил проверок) считается кодом и требует полного прогона.
• Полный прогон (full.yml, проверка full-run) запускается переводом PR из черновика в «готов» (gh pr ready). PR открывай черновиком (gh pr create --draft). Переводи в «готов» только когда быстрая часть зелёная и правки закончены. После новой отправки полный прогон для нового коммита запрашивается заново: gh pr ready --undo, затем gh pr ready. Без зелёного full-run PR не сливай, даже если check зелёный.
• Ставить статусы и проверки вручную через gh api (statuses, check-runs) запрещено: право на слияние даёт только задание GitHub Actions. В ruleset protect-main источник проверок check, full-run и windows-hooks закреплён как GitHub Actions (ADR-0013).

«Храповик» продукта (state/baseline.json): число тестов не должно уменьшаться, пропущенных тестов не должно появляться. Число тестов считается по полному сбору (pytest --collect-only -o addopts=), пропуски и падения берутся из отчёта полного прогона. Урезанный отчёт храповик принимает только в режиме --partial и baseline по нему не обновляет. Пока CI не зелёный (включая full-run), работа не закончена.

Правила (из BUILD_PLAN.md, раздел 2)

1. Одна фаза — одна ветка — один PR. В main напрямую не пушить.
2. Сначала документация (code.claude.com/docs), потом код. Расхождения с планом — в описание PR.
3. Целевая платформа — Windows 11, проверяется локально у владельца; CI на Linux проверяет переносимость. Hooks и скрипты — только Python 3, пути через pathlib.
4. Каждая проверка (hook, правило CI) имеет тест с заведомо плохим примером, который она обязана остановить.
5. Минимум файлов. Рабочих заметок и отчётов в репозитории нет; решения идут в docs/adr/.
6. Трудно отменяемые решения — ADR со статусом proposed, ждут утверждения владельца. Обратимые принимаешь сам, но тоже записываешь.
7. Описание PR — на русском: «Что сделано», «Какие решения приняты и почему», «Как проверить, что работает» (с выводом тестов).
8. Фаза не готова, пока CI не зелёный и не выполнены все критерии приёмки.
9. Если hook (или другая защита: permissions, правила путей) что-то заблокировал, не обходи это другим путём: переименованием файла, другим инструментом, командой оболочки или скриптом. Остановись, напиши владельцу, что заблокировано и зачем это нужно, и жди ответа. Разрешённые исключения записываются в ADR и действуют только для названного случая.
10. CI: Ubuntu по умолчанию; матрицы, не-Linux раннеры и запуск не по pull_request добавляются только через ADR с оценкой минут квоты за один прогон (Windows ×2, macOS ×10; ADR-0011).
11. Одновременно открыт только один PR. Следующий PR (и его ветку от main) начинай после слияния предыдущего: так открытые PR не устаревают после чужого слияния и не конфликтуют в state/baseline.json.
12. Имя ветки начинай с идентификатора блока из state/features.json (F13-…), если работа относится к блоку: по нему хуки определяют блок при петле и отчёте об инциденте. Работа вне блока: без префикса, отчёт называет NONE.
13. Файлы проекта пиши только инструментами Write и Edit: запись через командную строку (heredoc, >, tee, sed -i) запрещена хуком guard_shell_writes (исключения: отчёты тестов, покрытие, временные файлы вне проекта). Скрипт для работы с данными пиши файлом через Write и запускай командой.
14. Петля (три одинаковые ошибки подряд или правка туда-обратно) останавливает сессию: пиши отчёт по docs/INCIDENT_TEMPLATE.md и завершай сессию, продолжение только новой сессией.

Слияние PR (ADR-0003)

Ты сливаешь PR сам: gh pr merge --auto --squash (только Squash). Условия, все сразу:

1. Все обязательные проверки CI зелёные, а у PR с кодом зелёный и статус full-run (полный прогон, метка full).
2. В PR нет ADR со статусом proposed.
3. PR не меняет .github/, .claude/, plugin/hooks/, plugin/agents/, plugin/templates/ci/, tests/ (кроме добавления новых тестов), AGENTS.md, CLAUDE.md, requirements-dev.txt, state/baseline.json, state/acceptance/ (приёмка владельцем, ADR-0014), pyproject.toml в части правил проверок.
4. Описание PR заполнено по правилу 7.

Не выполнено хотя бы одно из 2–4: не сливай, напиши владельцу в чат одной строкой, что требует его решения, и жди ответа «сливай». Если автослияние отключено или нет прав, скажи об этом, не обходи.

Стиль

• Python: ruff (правила E,F,I,B,UP, длина строки 100), pyright в режиме strict, типы везде.
• Файлы в UTF-8, переводы строк LF (.gitattributes).
• Владелец продукта не программист. Всё, что адресовано ему (отчёты, ADR для утверждения, PR), пишется по-русски и на языке последствий: что изменится, что будет при ошибке, как откатить.