@AGENTS.md
This project is indexed by GitNexus as pythinker-code (196170 symbols, 756262 relationships, 1449 execution flows).
Index stale? Run
node .gitnexus/run.cjs analyze --index-onlyfrom the project root — it auto-selects an available runner. No.gitnexus/run.cjsyet? Bootstrap withnpx,bunx, orpnpm dlx— e.g.bunx gitnexus@latest analyze(npm 11 npx crash; #1939).
- MUST run impact before editing. Use
impact({target: "symbolName", direction: "upstream"})ornode .gitnexus/run.cjs impact "symbolName" --direction upstream --repo .; report callers, processes, and risk. Never substitute grep for graph analysis. - MUST analyze graph changes before committing. Use
detect_changes({scope: "all"})(MCP) ornode .gitnexus/run.cjs detect-changes --scope all --repo .(CLI fallback).partial: trueortruncated: trueis not a clean check — a zero means unseen, not unaffected; re-run it. For regression review:detect_changes({scope: "compare", base_ref: "main"})ornode .gitnexus/run.cjs detect-changes --scope compare --base-ref "main" --repo .. - MUST warn on HIGH/CRITICAL
riskpre-edit; never useriskSharedAxesto waive a HIGH/CRITICALriskwarning. Compare File/symbol: MCP File omits axes; Graph-RAG expands File. - MUST treat
risk: UNKNOWNas unresolved, not as low. An empty caller set is not evidence the symbol is unused — it can also mean the callers are not resolvable by the index (plain-object property access, dynamic dispatch, cross-language calls).impactpairsUNKNOWNwith ariskNotesaying so. Confirm with a text search before treating the symbol as safe to change or delete; do not proceed on the strength of a zero. - MUST use
query({search_query: "concept"})for concepts/flows,context({name: "symbolName"})for a named symbol, orimpactfor blast radius, on read-only callers, dependencies, imports, or execution flow. Graph first; text search only for empty/UNKNOWN/literals. - For security review,
explain({target: "fileOrSymbol"})lists taint findings (source→sink flows; needsanalyze --pdg).
- NEVER edit a function, class, or method before MCP/CLI impact analysis.
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read
UNKNOWNas an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means. - NEVER rename symbols with find-and-replace — use
renamewhich understands the call graph. - NEVER commit before MCP/CLI graph change analysis.
| Resource | Use for |
|---|---|
gitnexus://repo/pythinker-code/context |
Codebase overview, check index freshness |
gitnexus://repo/pythinker-code/clusters |
All functional areas |
gitnexus://repo/pythinker-code/processes |
All execution flows |
gitnexus://repo/pythinker-code/process/{name} |
Step-by-step execution trace |
| Task | Read this skill file |
|---|---|
| Understand architecture / "How does X work?" | .claude/skills/gitnexus-exploring/SKILL.md |
| Blast radius / "What breaks if I change X?" | .claude/skills/gitnexus-impact-analysis/SKILL.md |
| Trace bugs / "Why is X failing?" | .claude/skills/gitnexus-debugging/SKILL.md |
| Rename / extract / split / refactor | .claude/skills/gitnexus-refactoring/SKILL.md |
| Tools, resources, schema reference | .claude/skills/gitnexus-guide/SKILL.md |
| Index, status, clean, wiki CLI commands | .claude/skills/gitnexus-cli/SKILL.md |
GitHub Issues in this repo, driven through the gh CLI. See docs/agents/issue-tracker.md.
The five canonical roles: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. See docs/agents/triage-labels.md.
Single-context: root CONTEXT.md plus docs/adr/. See docs/agents/domain.md.