From 4cb0b8d450f5014446f2803828d1b97b6c19969f Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Thu, 25 Jun 2026 22:26:08 +0300 Subject: [PATCH] docs: clarify graphify usage for tracing --- AGENTS.md | 18 ++++++++++++------ README.md | 2 ++ 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0f46690..18d50be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -507,13 +507,19 @@ roadmap.md и inbox.md никогда не являются основанием ## graphify -This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. +This project has a knowledge graph in `graphify-out/` with god nodes, community structure, and cross-file relationships. The graph is a local artifact, not a tracked repo asset. When the user types `/graphify`, invoke the `skill` tool with `skill: "graphify"` before doing anything else. Rules: -- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. -- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it. -- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. -- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. -- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). +- Используй `graphify` в первую очередь, когда задача связана с архитектурой, границами модулей, кросс-файловым влиянием или трассировкой потока данных. +- Для таких вопросов сначала запускай `graphify query ""`, если существует `graphify-out/graph.json`. Для связей используй `graphify path "" ""`, для точечных концептов — `graphify explain ""`. Обычно это даёт гораздо более узкий подграф, чем `GRAPH_REPORT.md` или raw grep. +- Предпочитай `graphify query` перед raw grep, когда нужен кратчайший путь между концептами, мост между комьюнити или трассировка того, как один подсистемный блок достигает другого. +- Для отладки багов начинай с симптома и спрашивай у graphify путь зависимости, bridge nodes или модули, которые могут объяснить неожиданное поведение. +- Если `graphify` возвращает только общую структуру, переходи к `serena` за символ-уровневыми фактами и затем повторяй `graphify` с более узким вопросом, где названы конкретные файлы, модули или сервисы. +- Dirty `graphify-out/` после хуков или инкрементальных обновлений считаются нормой; грязные файлы графа не повод пропускать `graphify`. Пропускать его можно только если задача именно про устаревший или некорректный граф, либо если пользователь прямо попросил не использовать его. +- В новом `worktree` сначала заново создай локальный граф командой `graphify extract .`. +- После первой сборки в этом `worktree` обновляй граф командой `graphify update .`. +- Если существует `graphify-out/wiki/index.md`, используй его для широкого обзора вместо ручного просмотра исходников. +- `graphify-out/GRAPH_REPORT.md` читай только для широкого архитектурного обзора или когда `query/path/explain` не дают достаточно контекста. +- После изменений в коде запускай `graphify update .`, чтобы держать граф актуальным (только AST, без затрат на LLM). diff --git a/README.md b/README.md index 379051f..01a5cf9 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,8 @@ docs/ | `npm run format` | Prettier для всех `*.{ts,tsx}` | | `npm run codegen -w apps/frontend` | `openapi-typescript` из запущенного локального Swagger → `src/api/types.ts` | +`graphify-out/` — локальный артефакт знания, он не хранится в git. В новом `worktree` сначала собери его заново: `graphify extract .`; дальше обновляй инкрементально: `graphify update .`. Для вопросов по коду используй `graphify query "..."`. + Docusaurus (`apps/docs`) — опубликованная документация для пользователей. Storybook (`packages/design-system`) — инженерный workbench для разработки компонентов. Интеграционные тесты с MOEX: `npm run test:integration -w apps/backend`.