acquire-codebase-knowledge

Acquire Codebase Knowledge — официальный skill GitHub для картирования, документирования и onboarding в существующий репозиторий. Он запускается, когда нужно понять текущую кодовую базу, описать архитектуру или подготовить документацию проекта; для обычной реализации функции, узкого исправления бага или небольшого редактирования он не предназначен, если пользователь отдельно не просит repository-level discovery. Совместимость в исходной карточке указана как cross-platform; для запуска требуются Python 3.8+ и git, а scan.py выполняется из корня целевого проекта. Результат имеет жёсткий контракт: в docs/codebase/ должны появиться ровно семь файлов — STACK.md, STRUCTURE.md, ARCHITECTURE.md, CONVENTIONS.md, INTEGRATIONS.md, TESTING.md и CONCERNS.md. Каждый существенный вывод должен быть прослеживаем до исходного файла, конфигурации или вывода терминала. Неизвестные сведения помечаются [TODO], решения, зависящие от намерения команды, — [ASK USER], а каждый документ содержит короткий список evidence с конкретными путями файлов. В финальном сообщении skill требует перечислить нумерованные вопросы [ASK USER] и расхождения между заявленным намерением проекта и наблюдаемой реальностью. Workflow состоит из четырёх фаз. Сначала запускается scripts/scan.py с output docs/codebase/.codebase-scan.txt, затем ищутся и читаются PRD, TRD, README, ROADMAP, SPEC и DESIGN-файлы. До чтения исходников нужно сформулировать заявленное назначение проекта. На второй фазе исследуются семь областей документации; для подробного списка вопросов источник предлагает references/inquiry-checkpoints.md, а при неоднозначном стеке — references/stack-detection.md. Третья фаза заполняет документы в порядке от стека и структуры к архитектуре, конвенциям, интеграциям, тестированию и concerns. Четвёртая запускает цикл проверки: каждый нетривиальный тезис подтверждается evidence, пустые или неподдержанные секции исправляются, затем документы проверяются снова. В режиме focus area Phase 1 всё равно выполняется полностью. Сначала заполняются документы выбранной области, а в остальных сохраняется требуемая структура с [TODO]; после этого все семь файлов проходят общую валидацию. Это позволяет ограничить глубину работы, не выдавая непроверенную часть репозитория за готовую документацию. Важен и порядок доверия к источникам: устаревший README может описывать намерение, а не текущую архитектуру, поэтому его нужно сверять с фактическими файлами. Если в проекте есть несколько manifest-файлов, workspaces, packages или apps, каждый workspace следует рассматривать отдельно. Источник отдельно предупреждает о типовых ошибках. Не следует описывать dist, build, generated, .next, out или __pycache__ как исходные архитектурные шаблоны. TypeScript aliases из tsconfig paths нужно сопоставлять с реальными каталогами. Production-зависимости отделяются от devDependencies. Переменные из .env.example показывают форму конфигурации, но секреты не документируются. TODO в tests, test, __tests__ или spec следует считать пробелом покрытия, а не автоматически production debt. Файлы, которые часто менялись в git history, нужно отметить как потенциально хрупкие зоны, не объявляя их дефектными без доказательств. Встроенная проверка противостоит избыточным выводам: нельзя называть архитектуру Clean Architecture, если соответствующих слоёв нет, нельзя угадывать базу по имени переменной и нельзя выдавать намерение README за факт. Практический сценарий — запустить scan, прочитать документы намерения, собрать evidence для каждой области, заполнить семь файлов, заменить неизвестные места на [TODO] или [ASK USER], затем пройти validation loop. Skill создаёт проверяемую карту текущего репозитория, но не заменяет решение команды о целевой архитектуре и не доказывает корректность кода за пределами найденных источников.