/doc-lint — Аудит качества документации
<purpose> Сканирует все human-readable файлы проекта, находит проблемы с размером, структурой, дубликатами между файлами и нарушения SSOT (Single Source of Truth). Генерирует отчёт с приоритизированными findings и планом рефакторинга. </purpose>Перед началом
Прочитай .claude/qa_agent.md и .claude/agents/auditor.md.
Когда использовать
- •После добавления нового документа или skill
- •При подозрении на дублирование контента между файлами
- •Для периодического аудита документации (раз в спринт)
- •Перед рефакторингом документации
Входные данные
| Параметр | Обязательность | Описание |
|---|---|---|
| Scope | Опционально | Конкретные файлы/директории. По умолчанию — весь проект |
| Focus | Опционально | Только определённые фазы (size, structure, duplicates) |
Алгоритм (6 фаз)
Verbosity Protocol (STRICT)
SILENT MODE ENFORCED:
- •NO CHAT TABLES: Никогда не выводи таблицы (Inventory, Findings, Stats) в чат. Только в файл отчёта.
- •NO LISTS: Не перечисляй проверенные файлы в чате.
- •ONLY STATUS: В чат выводить только финальный блок
SKILL COMPLETEи путь к отчёту.
Пример единственного допустимого вывода в чат:
📝 Audit Complete. 📊 Report:
audit/doc-lint-report.md📉 Health Score: 78/100 💡 Action: Runbash audit/safe-fix.shto apply safe fixes.
Фазы 1-7: Детальный алгоритм
Полное описание всех фаз (Discovery, Size Analysis, Structure Analysis, Cross-File Duplicate Detection, Content Hygiene, Report Generation, Safe-Fix Script) — в references/phases.md.
Severity Model
| Severity | Критерии |
|---|---|
| CRITICAL | Фактическое превышение лимитов (>700 generic, >500 SKILL); Битые ссылки (файл не найден) |
| WARNING | Приближение к лимиту (90% от порога); Дубликаты >10 строк; Wall-of-text >30 строк |
| INFO | TODO маркеры; Мелкие дубликаты (3-5 строк); Stale dates; Formatting issues |
Health Score Logic
Start Score: 100.
Deductions (вычитание):
- •CRITICAL: -15 баллов (за каждый finding)
- •WARNING: -5 баллов
- •INFO: -0.5 балла (снижаем вес мусора)
Formula: MAX(0, 100 - (Count_Crit * 15) - (Count_Warn * 5) - (Count_Info * 0.5))
Бонусных баллов за "хорошее поведение" не начислять.
| Диапазон | Оценка | Интерпретация |
|---|---|---|
| 90-100 | Excellent | Документация в отличном состоянии |
| 70-89 | Good | Есть незначительные проблемы |
| 50-69 | Needs attention | Требуется рефакторинг |
| <50 | Refactoring needed | Срочный рефакторинг документации |
Формула должна быть показана с подстановкой значений:
code
Score = 100 - (2 × 15) - (5 × 5) - (8 × 0.5) = 100 - 30 - 25 - 4 = 41/100
Формат вывода
Артефакт: audit/doc-lint-report.md
markdown
# Doc-Lint Report
> Дата: {YYYY-MM-DD}
> Scope: {описание scope}
> Health Score: {N}/100 ({оценка})
## Summary
| Метрика | Значение |
|---------|----------|
| Файлов просканировано | N |
| CRITICAL | N |
| WARNING | N |
| INFO | N |
| Health Score | N/100 |
| Кластеров дубликатов | N |
## File Inventory
| # | Файл | Строк | Тип | Size Status |
|---|------|------:|-----|-------------|
| 1 | ... | ... | ... | OK/WARNING/CRITICAL |
## CRITICAL Findings
| # | Файл | Фаза | Описание | Рекомендация |
|---|------|------|----------|--------------|
## WARNING Findings
| # | Файл | Фаза | Описание | Рекомендация |
|---|------|------|----------|--------------|
## INFO Findings
| # | Файл | Фаза | Описание | Рекомендация |
|---|------|------|----------|--------------|
## Duplicate Map
### Кластер D-1: {название паттерна}
- **Тип:** Exact / Near-duplicate / Conceptual
- **SSOT Owner:** {файл}
- **Найдено в:** {список файлов с номерами строк}
- **Рекомендация:** Оставить в {Owner}, в остальных заменить ссылкой
### Кластер D-N: ...
## SSOT Refactoring Plan
| # | Действие | Файл | Что сделать |
|---|----------|------|-------------|
| 1 | REMOVE | file.md:10-25 | Удалить копию Tech Stack, добавить ссылку |
## Statistics
- Общий объём документации: {N} строк в {M} файлах
- Средний размер файла: {N/M} строк
- Файлов в пределах нормы: {X}/{M} = {%}
- Health Score: {формула с подстановкой}
Post-Check Scorecard
Формат Post-Check — аналогично /spec-audit (см. qa_agent.md § Skill Completion Protocol, qa_agent.md § Quality Gates).
Post-Check Scorecard:
markdown
## Scorecard
| Критерий | Результат |
|----------|-----------|
| Все файлы просканированы | X/Y = NN% |
| Line counts верифицированы | ✅/❌ |
| Cross-file detection выполнен | ✅/❌ |
| Каждый finding имеет severity + рекомендацию | X/Y = NN% |
| Нет placeholder {xxx} | ✅/❌ |
| SSOT owner назначен для каждого кластера | X/Y = NN% |
| Формулы с числителем/знаменателем | ✅/❌ |
### Итоговый Score: NN%
Quality Gates
- • Все файлы в scope отсканированы (Glob + count verification)
- • Line counts верифицированы через
wc -l - • Cross-file duplicate detection выполнен (Фаза 4)
- • Каждый finding имеет severity + рекомендацию
- • Нет placeholder
{xxx}в отчёте - • SSOT owner назначен для каждого кластера дубликатов
- • Формулы показаны с числителем и знаменателем (CLAUDE.md requirement)
- • Health Score рассчитан и показан с подстановкой
Anti-Patterns (BANNED)
False Positive на одинаковых заголовках
code
❌ Flagging таблиц с одинаковыми заголовками но разными данными как "duplicate" ✅ Сравнивать содержимое ячеек, не только headers
Phantom Findings
code
❌ Генерировать findings на основе предположений без чтения файла ✅ Каждый finding подтверждён содержимым файла (строка, фрагмент)
Missing Context
code
❌ "File is too long" ✅ "CLAUDE.md: 305 строк > порог CRITICAL (300). Рекомендация: вынести секцию X в qa_agent.md"
Over-flagging Intentional Repetition
code
❌ Flagging ссылок на паттерны как дубликатов (ссылки — не дубликаты) ✅ Отличать полное копирование от ссылок и краткого упоминания
Связанные файлы
| Файл | Содержание |
|---|---|
references/check-rules.md | Пороги размеров, сигнатуры дубликатов, SSOT-матрица, Diataxis-маркеры |
references/best-practices.md | Корпоративные практики: Google, Amazon, Diataxis, Microsoft, GitLab, Stripe |
Завершение
После создания отчёта и скрипта — напечатай блок SKILL COMPLETE (формат в qa_agent.md § Skill Completion Protocol).
code
✅ SKILL COMPLETE: /doc-lint
├─ Артефакты: audit/doc-lint-report.md, audit/safe-fix.sh
├─ Compilation: N/A
├─ Upstream: нет
└─ Score: {Health Score}/100