13942526a1
* feat(skills): add audit skill for one-command project audit * feat(commands): add /audit command as thin wrapper for audit skill --------- Co-authored-by: opencode-agent <agent@opencode.local>
148 lines
No EOL
9.1 KiB
Markdown
148 lines
No EOL
9.1 KiB
Markdown
---
|
||
name: audit
|
||
description: One-command project audit. project-status tool + explore subagent (code-standards) → binary verdict → ask user → create-issue for each problem. Read-only (creates issues, NOT fixes). Also when user says "аудит проекта", "проверь проект", "audit", "проверь архитектуру".
|
||
---
|
||
|
||
# Audit
|
||
|
||
Линейный flow для аудита существующего проекта. В отличие от
|
||
`project-template` check flow (который чинит через FIX subagents напрямую),
|
||
audit создаёт **GitHub issues** для рефакторинга — дальше юзер запускает
|
||
`/run-pipeline` на каждом issue (pipeline-подход: ISSUE → IMPLEMENT → CI →
|
||
REVIEW → MERGE).
|
||
|
||
Источники находок:
|
||
- **`project-status` tool** — детерминированные проблемы (нет `conftest.py`,
|
||
нет `ci.yml`, thin routes, centralized models). Agent парсит текстовый
|
||
отчёт (НЕ JSON — `project-status.py` не трогаем).
|
||
- **`explore` subagent + `code-standards` skill** — качественные проблемы
|
||
(`project-status` НЕ ловит): schemas смешаны с models, бизнес-логика в
|
||
роутах, нарушение layering, service-слой пропущен.
|
||
|
||
## ПРОТОКОЛ (ЖЁСТКО)
|
||
|
||
1. **`project-status({})`** — оркестратор вызывает tool напрямую (read-only
|
||
oracle, ALLOWED — как `pipeline-status` / `spec-status`). Если вернул
|
||
`⚠️ ...failed` → WARN, продолжай без детерминированных находок (explore
|
||
всё равно работает).
|
||
2. **Парсит отчёт** (текст): `Итог:` (OK/WARN/FAIL counts) + `Рекомендации:`
|
||
(список FAIL с путями).
|
||
3. **`skill({ name: "code-standards" })`** — load skill (НЕ хардкод правил в
|
||
audit skill — `code-standards` источник правды).
|
||
4. **Delegate `explore` subagent** (Template EXPLORE) — проверяет структуру
|
||
и код против `code-standards`, возвращает
|
||
`[{category, problem, path, severity}, ...]`.
|
||
5. **Комбинирует** находки: FAIL/WARN из `project-status` + качественные из
|
||
explore. **Дедупликация**: если `project-status` FAIL и explore нашли
|
||
одну и ту же проблему → 1 issue (не 2).
|
||
6. **Бинарный вердикт**:
|
||
- `≥1 FAIL` ИЛИ `≥1 qualitative finding` → `❌ Найдено N проблем`
|
||
- `0 FAIL` + `0 qualitative` + `0 WARN` → `✅ Проект здоров` → STOP
|
||
- `0 FAIL` + `0 qualitative` + `≥1 WARN` → `⚠️ N замечаний` → вопрос
|
||
7. **Список проблем** (сгруппированный: Структура / Качество / Тесты / Infra
|
||
/ Code-standards) — покажи юзеру.
|
||
8. **Вопрос юзеру**:
|
||
```
|
||
Найдено N проблем. Создать issues для рефакторинга?
|
||
[1] да — для каждой проблемы create-issue (subagent)
|
||
[2] нет — STOP, отчёт у юзера
|
||
```
|
||
9. Если `да` → для **каждой** проблемы (последовательно, НЕ параллельно —
|
||
Linear Execution из AGENTS.md) — delegate `task(general)` с Template
|
||
ISSUE_CREATE. Если `create-issue` валидация упала → subagent сообщает
|
||
ошибку, continue к следующей. Если gh недоступен → STOP + report.
|
||
10. **Финальный репорт**:
|
||
```
|
||
Audit complete. Создано N issues:
|
||
- #M1: <title> — <url>
|
||
Запусти /run-pipeline на каждом issue для рефакторинга.
|
||
```
|
||
|
||
### ЗАПРЕЩЕНО
|
||
|
||
- Чинить код напрямую (audit = read-only, только issues). FIX flow остаётся
|
||
в `project-template` check flow.
|
||
- Параллелить create-issue subagents (Linear Execution).
|
||
- Хардкодить правила из `code-standards` — загружай через `skill()`.
|
||
- Трогать `project-status.py` (агент парсит текст — JSON не нужен).
|
||
- Создавать `audit-status` tool (audit — линейный, не фазный loop).
|
||
- Группировать проблемы в один issue (1 проблема = 1 issue для `/run-pipeline`).
|
||
|
||
## Граничные случаи
|
||
|
||
- **Репо UNKNOWN типа** → explore всё равно проверяет против
|
||
`code-standards`, вердикт по качественным находкам.
|
||
- **Репо без `src/<pkg>/`** (flat layout) → `project-status` WARNs, explore
|
||
проверяет по `code-standards` (если применимо).
|
||
- **Только WARN** (0 FAIL, 0 qualitative) → `⚠️ N замечаний`, вопрос (да/нет
|
||
— на усмотрение юзера).
|
||
- **Юзер "нет"** → STOP, отчёт у юзера.
|
||
- **create-issue валидация упала** → subagent сообщает, continue к следующей.
|
||
- **Дублирующие проблемы** → дедупликация оркестратором (1 issue, не 2).
|
||
|
||
## Prompt templates
|
||
|
||
### Template EXPLORE (code-standards qualitative audit)
|
||
|
||
```
|
||
Прочитай .opencode/skills/code-standards/SKILL.md.
|
||
Проверь структуру и код проекта в <cwd> против правил из skill.
|
||
Найди качественные проблемы, которые project-status НЕ ловит:
|
||
- schemas смешаны с models (Pydantic DTO в db/models/)
|
||
- бизнес-логика в роутах (Tortoise queries в api/)
|
||
- нарушение layering (routes импортируют db/models напрямую, минуя services)
|
||
- service-слой пропущен (routes → db/models без services/)
|
||
- файлы длиннее 200-300 строк (декомпозиция)
|
||
- mixing concerns (бизнес-логика ≠ транспорт ≠ представление)
|
||
|
||
Для каждой находки верни:
|
||
{category: "Code-standards", problem: "<name>: <detail>", path: "<file:line>", severity: "warn"|"fail"}
|
||
|
||
Верни массив находок. Если находок нет — пустой массив [].
|
||
НЕ редактируй код — audit read-only. Только отчёт.
|
||
```
|
||
|
||
### Template ISSUE_CREATE (create-issue для одной проблемы)
|
||
|
||
```
|
||
Создай GitHub issue для проблемы из audit.
|
||
Категория: <category>
|
||
Проблема: <name>: <detail>
|
||
Путь: <path>
|
||
Источник: <project-status | code-standards explore>
|
||
Severity: <warn|fail>
|
||
|
||
1. Load `issue` skill via `skill({ name: "issue" })`.
|
||
2. Сформируй issue body (8 headings: ## Контекст, ## Задача, ## Контракты,
|
||
## Инварианты, ## Граничные случаи, ## Вне scope, ## Критерии приемки).
|
||
- Контекст: проблема из audit (<repo>) — <name>: <detail>. Путь: <path>.
|
||
Источник: <source>. Severity: <severity>.
|
||
- Задача: что починить (конкретно, с путями к файлам).
|
||
- Контракты: конкретные изменения (что должно стать после фикса).
|
||
- Инварианты: что НЕ ломать при фиксе.
|
||
- Граничные случаи: edge cases при фиксе.
|
||
- Вне scope: что НЕ делаем в этом issue.
|
||
- Критерии приемки: чек-лист (включая `project-status` проходит эту
|
||
категорию после фикса).
|
||
3. `create-issue({ title: "fix(<scope>): <description>", body, labels: ["tech-debt", "from-audit"] })`
|
||
tool (НЕ raw `gh issue create` — заблокирован deny). tool валидирует
|
||
conventional title + 7 headings + Cyrillic.
|
||
4. Верни: issue URL (или ошибку валидации для оркестратора).
|
||
|
||
Если gh недоступен → верни: "gh unavailable: <reason>". НЕ retry, НЕ fallback.
|
||
```
|
||
|
||
## Rules
|
||
|
||
- Main agent = оркестратор: `project-status` tool + `explore` subagent +
|
||
вопрос юзеру + `task(general)` для create-issue. Не делает
|
||
edit/read/`gh issue create` сам.
|
||
- `project-status` — read-only oracle, ALLOWED для оркестратора.
|
||
- Audit — read-only (НЕ редактирует код, только создаёт issues).
|
||
- FAIL/WARN из `project-status` → issues, НЕ FIX напрямую.
|
||
- 1 проблема = 1 issue (для отдельного `/run-pipeline`).
|
||
- Issue body self-contained (8 headings, `create-issue` валидация).
|
||
- `code-standards` — через `skill()` tool, НЕ хардкод.
|
||
- Audit — линейный flow (не `audit-status` tool).
|
||
- create-issue subagents — последовательно (Linear Execution).
|
||
- Subagent error → 1 retry, потом STOP + report. |