秦汉
4 weeks ago
9 changed files with 735 additions and 0 deletions
@ -0,0 +1,82 @@ |
|||||
|
--- |
||||
|
name: gitnexus-cli |
||||
|
description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\"" |
||||
|
--- |
||||
|
|
||||
|
# GitNexus CLI Commands |
||||
|
|
||||
|
All commands work via `npx` — no global install required. |
||||
|
|
||||
|
## Commands |
||||
|
|
||||
|
### analyze — Build or refresh the index |
||||
|
|
||||
|
```bash |
||||
|
npx gitnexus analyze |
||||
|
``` |
||||
|
|
||||
|
Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files. |
||||
|
|
||||
|
| Flag | Effect | |
||||
|
| -------------- | ---------------------------------------------------------------- | |
||||
|
| `--force` | Force full re-index even if up to date | |
||||
|
| `--embeddings` | Enable embedding generation for semantic search (off by default) | |
||||
|
|
||||
|
**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated. |
||||
|
|
||||
|
### status — Check index freshness |
||||
|
|
||||
|
```bash |
||||
|
npx gitnexus status |
||||
|
``` |
||||
|
|
||||
|
Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed. |
||||
|
|
||||
|
### clean — Delete the index |
||||
|
|
||||
|
```bash |
||||
|
npx gitnexus clean |
||||
|
``` |
||||
|
|
||||
|
Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project. |
||||
|
|
||||
|
| Flag | Effect | |
||||
|
| --------- | ------------------------------------------------- | |
||||
|
| `--force` | Skip confirmation prompt | |
||||
|
| `--all` | Clean all indexed repos, not just the current one | |
||||
|
|
||||
|
### wiki — Generate documentation from the graph |
||||
|
|
||||
|
```bash |
||||
|
npx gitnexus wiki |
||||
|
``` |
||||
|
|
||||
|
Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use). |
||||
|
|
||||
|
| Flag | Effect | |
||||
|
| ------------------- | ----------------------------------------- | |
||||
|
| `--force` | Force full regeneration | |
||||
|
| `--model <model>` | LLM model (default: minimax/minimax-m2.5) | |
||||
|
| `--base-url <url>` | LLM API base URL | |
||||
|
| `--api-key <key>` | LLM API key | |
||||
|
| `--concurrency <n>` | Parallel LLM calls (default: 3) | |
||||
|
| `--gist` | Publish wiki as a public GitHub Gist | |
||||
|
|
||||
|
### list — Show all indexed repos |
||||
|
|
||||
|
```bash |
||||
|
npx gitnexus list |
||||
|
``` |
||||
|
|
||||
|
Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information. |
||||
|
|
||||
|
## After Indexing |
||||
|
|
||||
|
1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded |
||||
|
2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task |
||||
|
|
||||
|
## Troubleshooting |
||||
|
|
||||
|
- **"Not inside a git repository"**: Run from a directory inside a git repo |
||||
|
- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server |
||||
|
- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding |
||||
@ -0,0 +1,89 @@ |
|||||
|
--- |
||||
|
name: gitnexus-debugging |
||||
|
description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\"" |
||||
|
--- |
||||
|
|
||||
|
# Debugging with GitNexus |
||||
|
|
||||
|
## When to Use |
||||
|
|
||||
|
- "Why is this function failing?" |
||||
|
- "Trace where this error comes from" |
||||
|
- "Who calls this method?" |
||||
|
- "This endpoint returns 500" |
||||
|
- Investigating bugs, errors, or unexpected behavior |
||||
|
|
||||
|
## Workflow |
||||
|
|
||||
|
``` |
||||
|
1. gitnexus_query({query: "<error or symptom>"}) → Find related execution flows |
||||
|
2. gitnexus_context({name: "<suspect>"}) → See callers/callees/processes |
||||
|
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow |
||||
|
4. gitnexus_cypher({query: "MATCH path..."}) → Custom traces if needed |
||||
|
``` |
||||
|
|
||||
|
> If "Index is stale" → run `npx gitnexus analyze` in terminal. |
||||
|
|
||||
|
## Checklist |
||||
|
|
||||
|
``` |
||||
|
- [ ] Understand the symptom (error message, unexpected behavior) |
||||
|
- [ ] gitnexus_query for error text or related code |
||||
|
- [ ] Identify the suspect function from returned processes |
||||
|
- [ ] gitnexus_context to see callers and callees |
||||
|
- [ ] Trace execution flow via process resource if applicable |
||||
|
- [ ] gitnexus_cypher for custom call chain traces if needed |
||||
|
- [ ] Read source files to confirm root cause |
||||
|
``` |
||||
|
|
||||
|
## Debugging Patterns |
||||
|
|
||||
|
| Symptom | GitNexus Approach | |
||||
|
| -------------------- | ---------------------------------------------------------- | |
||||
|
| Error message | `gitnexus_query` for error text → `context` on throw sites | |
||||
|
| Wrong return value | `context` on the function → trace callees for data flow | |
||||
|
| Intermittent failure | `context` → look for external calls, async deps | |
||||
|
| Performance issue | `context` → find symbols with many callers (hot paths) | |
||||
|
| Recent regression | `detect_changes` to see what your changes affect | |
||||
|
|
||||
|
## Tools |
||||
|
|
||||
|
**gitnexus_query** — find code related to error: |
||||
|
|
||||
|
``` |
||||
|
gitnexus_query({query: "payment validation error"}) |
||||
|
→ Processes: CheckoutFlow, ErrorHandling |
||||
|
→ Symbols: validatePayment, handlePaymentError, PaymentException |
||||
|
``` |
||||
|
|
||||
|
**gitnexus_context** — full context for a suspect: |
||||
|
|
||||
|
``` |
||||
|
gitnexus_context({name: "validatePayment"}) |
||||
|
→ Incoming calls: processCheckout, webhookHandler |
||||
|
→ Outgoing calls: verifyCard, fetchRates (external API!) |
||||
|
→ Processes: CheckoutFlow (step 3/7) |
||||
|
``` |
||||
|
|
||||
|
**gitnexus_cypher** — custom call chain traces: |
||||
|
|
||||
|
```cypher |
||||
|
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"}) |
||||
|
RETURN [n IN nodes(path) | n.name] AS chain |
||||
|
``` |
||||
|
|
||||
|
## Example: "Payment endpoint returns 500 intermittently" |
||||
|
|
||||
|
``` |
||||
|
1. gitnexus_query({query: "payment error handling"}) |
||||
|
→ Processes: CheckoutFlow, ErrorHandling |
||||
|
→ Symbols: validatePayment, handlePaymentError |
||||
|
|
||||
|
2. gitnexus_context({name: "validatePayment"}) |
||||
|
→ Outgoing calls: verifyCard, fetchRates (external API!) |
||||
|
|
||||
|
3. READ gitnexus://repo/my-app/process/CheckoutFlow |
||||
|
→ Step 3: validatePayment → calls fetchRates (external) |
||||
|
|
||||
|
4. Root cause: fetchRates calls external API without proper timeout |
||||
|
``` |
||||
@ -0,0 +1,78 @@ |
|||||
|
--- |
||||
|
name: gitnexus-exploring |
||||
|
description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\"" |
||||
|
--- |
||||
|
|
||||
|
# Exploring Codebases with GitNexus |
||||
|
|
||||
|
## When to Use |
||||
|
|
||||
|
- "How does authentication work?" |
||||
|
- "What's the project structure?" |
||||
|
- "Show me the main components" |
||||
|
- "Where is the database logic?" |
||||
|
- Understanding code you haven't seen before |
||||
|
|
||||
|
## Workflow |
||||
|
|
||||
|
``` |
||||
|
1. READ gitnexus://repos → Discover indexed repos |
||||
|
2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness |
||||
|
3. gitnexus_query({query: "<what you want to understand>"}) → Find related execution flows |
||||
|
4. gitnexus_context({name: "<symbol>"}) → Deep dive on specific symbol |
||||
|
5. READ gitnexus://repo/{name}/process/{name} → Trace full execution flow |
||||
|
``` |
||||
|
|
||||
|
> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal. |
||||
|
|
||||
|
## Checklist |
||||
|
|
||||
|
``` |
||||
|
- [ ] READ gitnexus://repo/{name}/context |
||||
|
- [ ] gitnexus_query for the concept you want to understand |
||||
|
- [ ] Review returned processes (execution flows) |
||||
|
- [ ] gitnexus_context on key symbols for callers/callees |
||||
|
- [ ] READ process resource for full execution traces |
||||
|
- [ ] Read source files for implementation details |
||||
|
``` |
||||
|
|
||||
|
## Resources |
||||
|
|
||||
|
| Resource | What you get | |
||||
|
| --------------------------------------- | ------------------------------------------------------- | |
||||
|
| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) | |
||||
|
| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) | |
||||
|
| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) | |
||||
|
| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) | |
||||
|
|
||||
|
## Tools |
||||
|
|
||||
|
**gitnexus_query** — find execution flows related to a concept: |
||||
|
|
||||
|
``` |
||||
|
gitnexus_query({query: "payment processing"}) |
||||
|
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler |
||||
|
→ Symbols grouped by flow with file locations |
||||
|
``` |
||||
|
|
||||
|
**gitnexus_context** — 360-degree view of a symbol: |
||||
|
|
||||
|
``` |
||||
|
gitnexus_context({name: "validateUser"}) |
||||
|
→ Incoming calls: loginHandler, apiMiddleware |
||||
|
→ Outgoing calls: checkToken, getUserById |
||||
|
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3) |
||||
|
``` |
||||
|
|
||||
|
## Example: "How does payment processing work?" |
||||
|
|
||||
|
``` |
||||
|
1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes |
||||
|
2. gitnexus_query({query: "payment processing"}) |
||||
|
→ CheckoutFlow: processPayment → validateCard → chargeStripe |
||||
|
→ RefundFlow: initiateRefund → calculateRefund → processRefund |
||||
|
3. gitnexus_context({name: "processPayment"}) |
||||
|
→ Incoming: checkoutHandler, webhookHandler |
||||
|
→ Outgoing: validateCard, chargeStripe, saveTransaction |
||||
|
4. Read src/payments/processor.ts for implementation details |
||||
|
``` |
||||
@ -0,0 +1,64 @@ |
|||||
|
--- |
||||
|
name: gitnexus-guide |
||||
|
description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\"" |
||||
|
--- |
||||
|
|
||||
|
# GitNexus Guide |
||||
|
|
||||
|
Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema. |
||||
|
|
||||
|
## Always Start Here |
||||
|
|
||||
|
For any task involving code understanding, debugging, impact analysis, or refactoring: |
||||
|
|
||||
|
1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness |
||||
|
2. **Match your task to a skill below** and **read that skill file** |
||||
|
3. **Follow the skill's workflow and checklist** |
||||
|
|
||||
|
> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first. |
||||
|
|
||||
|
## Skills |
||||
|
|
||||
|
| Task | Skill to read | |
||||
|
| -------------------------------------------- | ------------------- | |
||||
|
| Understand architecture / "How does X work?" | `gitnexus-exploring` | |
||||
|
| Blast radius / "What breaks if I change X?" | `gitnexus-impact-analysis` | |
||||
|
| Trace bugs / "Why is X failing?" | `gitnexus-debugging` | |
||||
|
| Rename / extract / split / refactor | `gitnexus-refactoring` | |
||||
|
| Tools, resources, schema reference | `gitnexus-guide` (this file) | |
||||
|
| Index, status, clean, wiki CLI commands | `gitnexus-cli` | |
||||
|
|
||||
|
## Tools Reference |
||||
|
|
||||
|
| Tool | What it gives you | |
||||
|
| ---------------- | ------------------------------------------------------------------------ | |
||||
|
| `query` | Process-grouped code intelligence — execution flows related to a concept | |
||||
|
| `context` | 360-degree symbol view — categorized refs, processes it participates in | |
||||
|
| `impact` | Symbol blast radius — what breaks at depth 1/2/3 with confidence | |
||||
|
| `detect_changes` | Git-diff impact — what do your current changes affect | |
||||
|
| `rename` | Multi-file coordinated rename with confidence-tagged edits | |
||||
|
| `cypher` | Raw graph queries (read `gitnexus://repo/{name}/schema` first) | |
||||
|
| `list_repos` | Discover indexed repos | |
||||
|
|
||||
|
## Resources Reference |
||||
|
|
||||
|
Lightweight reads (~100-500 tokens) for navigation: |
||||
|
|
||||
|
| Resource | Content | |
||||
|
| ---------------------------------------------- | ----------------------------------------- | |
||||
|
| `gitnexus://repo/{name}/context` | Stats, staleness check | |
||||
|
| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores | |
||||
|
| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members | |
||||
|
| `gitnexus://repo/{name}/processes` | All execution flows | |
||||
|
| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace | |
||||
|
| `gitnexus://repo/{name}/schema` | Graph schema for Cypher | |
||||
|
|
||||
|
## Graph Schema |
||||
|
|
||||
|
**Nodes:** File, Function, Class, Interface, Method, Community, Process |
||||
|
**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS |
||||
|
|
||||
|
```cypher |
||||
|
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"}) |
||||
|
RETURN caller.name, caller.filePath |
||||
|
``` |
||||
@ -0,0 +1,97 @@ |
|||||
|
--- |
||||
|
name: gitnexus-impact-analysis |
||||
|
description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\"" |
||||
|
--- |
||||
|
|
||||
|
# Impact Analysis with GitNexus |
||||
|
|
||||
|
## When to Use |
||||
|
|
||||
|
- "Is it safe to change this function?" |
||||
|
- "What will break if I modify X?" |
||||
|
- "Show me the blast radius" |
||||
|
- "Who uses this code?" |
||||
|
- Before making non-trivial code changes |
||||
|
- Before committing — to understand what your changes affect |
||||
|
|
||||
|
## Workflow |
||||
|
|
||||
|
``` |
||||
|
1. gitnexus_impact({target: "X", direction: "upstream"}) → What depends on this |
||||
|
2. READ gitnexus://repo/{name}/processes → Check affected execution flows |
||||
|
3. gitnexus_detect_changes() → Map current git changes to affected flows |
||||
|
4. Assess risk and report to user |
||||
|
``` |
||||
|
|
||||
|
> If "Index is stale" → run `npx gitnexus analyze` in terminal. |
||||
|
|
||||
|
## Checklist |
||||
|
|
||||
|
``` |
||||
|
- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents |
||||
|
- [ ] Review d=1 items first (these WILL BREAK) |
||||
|
- [ ] Check high-confidence (>0.8) dependencies |
||||
|
- [ ] READ processes to check affected execution flows |
||||
|
- [ ] gitnexus_detect_changes() for pre-commit check |
||||
|
- [ ] Assess risk level and report to user |
||||
|
``` |
||||
|
|
||||
|
## Understanding Output |
||||
|
|
||||
|
| Depth | Risk Level | Meaning | |
||||
|
| ----- | ---------------- | ------------------------ | |
||||
|
| d=1 | **WILL BREAK** | Direct callers/importers | |
||||
|
| d=2 | LIKELY AFFECTED | Indirect dependencies | |
||||
|
| d=3 | MAY NEED TESTING | Transitive effects | |
||||
|
|
||||
|
## Risk Assessment |
||||
|
|
||||
|
| Affected | Risk | |
||||
|
| ------------------------------ | -------- | |
||||
|
| <5 symbols, few processes | LOW | |
||||
|
| 5-15 symbols, 2-5 processes | MEDIUM | |
||||
|
| >15 symbols or many processes | HIGH | |
||||
|
| Critical path (auth, payments) | CRITICAL | |
||||
|
|
||||
|
## Tools |
||||
|
|
||||
|
**gitnexus_impact** — the primary tool for symbol blast radius: |
||||
|
|
||||
|
``` |
||||
|
gitnexus_impact({ |
||||
|
target: "validateUser", |
||||
|
direction: "upstream", |
||||
|
minConfidence: 0.8, |
||||
|
maxDepth: 3 |
||||
|
}) |
||||
|
|
||||
|
→ d=1 (WILL BREAK): |
||||
|
- loginHandler (src/auth/login.ts:42) [CALLS, 100%] |
||||
|
- apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%] |
||||
|
|
||||
|
→ d=2 (LIKELY AFFECTED): |
||||
|
- authRouter (src/routes/auth.ts:22) [CALLS, 95%] |
||||
|
``` |
||||
|
|
||||
|
**gitnexus_detect_changes** — git-diff based impact analysis: |
||||
|
|
||||
|
``` |
||||
|
gitnexus_detect_changes({scope: "staged"}) |
||||
|
|
||||
|
→ Changed: 5 symbols in 3 files |
||||
|
→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline |
||||
|
→ Risk: MEDIUM |
||||
|
``` |
||||
|
|
||||
|
## Example: "What breaks if I change validateUser?" |
||||
|
|
||||
|
``` |
||||
|
1. gitnexus_impact({target: "validateUser", direction: "upstream"}) |
||||
|
→ d=1: loginHandler, apiMiddleware (WILL BREAK) |
||||
|
→ d=2: authRouter, sessionManager (LIKELY AFFECTED) |
||||
|
|
||||
|
2. READ gitnexus://repo/my-app/processes |
||||
|
→ LoginFlow and TokenRefresh touch validateUser |
||||
|
|
||||
|
3. Risk: 2 direct callers, 2 processes = MEDIUM |
||||
|
``` |
||||
@ -0,0 +1,121 @@ |
|||||
|
--- |
||||
|
name: gitnexus-refactoring |
||||
|
description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\"" |
||||
|
--- |
||||
|
|
||||
|
# Refactoring with GitNexus |
||||
|
|
||||
|
## When to Use |
||||
|
|
||||
|
- "Rename this function safely" |
||||
|
- "Extract this into a module" |
||||
|
- "Split this service" |
||||
|
- "Move this to a new file" |
||||
|
- Any task involving renaming, extracting, splitting, or restructuring code |
||||
|
|
||||
|
## Workflow |
||||
|
|
||||
|
``` |
||||
|
1. gitnexus_impact({target: "X", direction: "upstream"}) → Map all dependents |
||||
|
2. gitnexus_query({query: "X"}) → Find execution flows involving X |
||||
|
3. gitnexus_context({name: "X"}) → See all incoming/outgoing refs |
||||
|
4. Plan update order: interfaces → implementations → callers → tests |
||||
|
``` |
||||
|
|
||||
|
> If "Index is stale" → run `npx gitnexus analyze` in terminal. |
||||
|
|
||||
|
## Checklists |
||||
|
|
||||
|
### Rename Symbol |
||||
|
|
||||
|
``` |
||||
|
- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits |
||||
|
- [ ] Review graph edits (high confidence) and ast_search edits (review carefully) |
||||
|
- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits |
||||
|
- [ ] gitnexus_detect_changes() — verify only expected files changed |
||||
|
- [ ] Run tests for affected processes |
||||
|
``` |
||||
|
|
||||
|
### Extract Module |
||||
|
|
||||
|
``` |
||||
|
- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs |
||||
|
- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers |
||||
|
- [ ] Define new module interface |
||||
|
- [ ] Extract code, update imports |
||||
|
- [ ] gitnexus_detect_changes() — verify affected scope |
||||
|
- [ ] Run tests for affected processes |
||||
|
``` |
||||
|
|
||||
|
### Split Function/Service |
||||
|
|
||||
|
``` |
||||
|
- [ ] gitnexus_context({name: target}) — understand all callees |
||||
|
- [ ] Group callees by responsibility |
||||
|
- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update |
||||
|
- [ ] Create new functions/services |
||||
|
- [ ] Update callers |
||||
|
- [ ] gitnexus_detect_changes() — verify affected scope |
||||
|
- [ ] Run tests for affected processes |
||||
|
``` |
||||
|
|
||||
|
## Tools |
||||
|
|
||||
|
**gitnexus_rename** — automated multi-file rename: |
||||
|
|
||||
|
``` |
||||
|
gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true}) |
||||
|
→ 12 edits across 8 files |
||||
|
→ 10 graph edits (high confidence), 2 ast_search edits (review) |
||||
|
→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}] |
||||
|
``` |
||||
|
|
||||
|
**gitnexus_impact** — map all dependents first: |
||||
|
|
||||
|
``` |
||||
|
gitnexus_impact({target: "validateUser", direction: "upstream"}) |
||||
|
→ d=1: loginHandler, apiMiddleware, testUtils |
||||
|
→ Affected Processes: LoginFlow, TokenRefresh |
||||
|
``` |
||||
|
|
||||
|
**gitnexus_detect_changes** — verify your changes after refactoring: |
||||
|
|
||||
|
``` |
||||
|
gitnexus_detect_changes({scope: "all"}) |
||||
|
→ Changed: 8 files, 12 symbols |
||||
|
→ Affected processes: LoginFlow, TokenRefresh |
||||
|
→ Risk: MEDIUM |
||||
|
``` |
||||
|
|
||||
|
**gitnexus_cypher** — custom reference queries: |
||||
|
|
||||
|
```cypher |
||||
|
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"}) |
||||
|
RETURN caller.name, caller.filePath ORDER BY caller.filePath |
||||
|
``` |
||||
|
|
||||
|
## Risk Rules |
||||
|
|
||||
|
| Risk Factor | Mitigation | |
||||
|
| ------------------- | ----------------------------------------- | |
||||
|
| Many callers (>5) | Use gitnexus_rename for automated updates | |
||||
|
| Cross-area refs | Use detect_changes after to verify scope | |
||||
|
| String/dynamic refs | gitnexus_query to find them | |
||||
|
| External/public API | Version and deprecate properly | |
||||
|
|
||||
|
## Example: Rename `validateUser` to `authenticateUser` |
||||
|
|
||||
|
``` |
||||
|
1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true}) |
||||
|
→ 12 edits: 10 graph (safe), 2 ast_search (review) |
||||
|
→ Files: validator.ts, login.ts, middleware.ts, config.json... |
||||
|
|
||||
|
2. Review ast_search edits (config.json: dynamic reference!) |
||||
|
|
||||
|
3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false}) |
||||
|
→ Applied 12 edits across 8 files |
||||
|
|
||||
|
4. gitnexus_detect_changes({scope: "all"}) |
||||
|
→ Affected: LoginFlow, TokenRefresh |
||||
|
→ Risk: MEDIUM — run tests for these flows |
||||
|
``` |
||||
@ -1 +1,2 @@ |
|||||
.gitnexus |
.gitnexus |
||||
|
/AGENTS.md |
||||
|
|||||
@ -0,0 +1,101 @@ |
|||||
|
<!-- gitnexus:start --> |
||||
|
# GitNexus — Code Intelligence |
||||
|
|
||||
|
This project is indexed by GitNexus as **Build_God** (678 symbols, 972 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. |
||||
|
|
||||
|
> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. |
||||
|
|
||||
|
## Always Do |
||||
|
|
||||
|
- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user. |
||||
|
- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. |
||||
|
- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits. |
||||
|
- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance. |
||||
|
- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`. |
||||
|
|
||||
|
## When Debugging |
||||
|
|
||||
|
1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue |
||||
|
2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation |
||||
|
3. `READ gitnexus://repo/Build_God/process/{processName}` — trace the full execution flow step by step |
||||
|
4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed |
||||
|
|
||||
|
## When Refactoring |
||||
|
|
||||
|
- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`. |
||||
|
- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code. |
||||
|
- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed. |
||||
|
|
||||
|
## Never Do |
||||
|
|
||||
|
- NEVER edit a function, class, or method without first running `gitnexus_impact` on it. |
||||
|
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis. |
||||
|
- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph. |
||||
|
- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope. |
||||
|
|
||||
|
## Tools Quick Reference |
||||
|
|
||||
|
| Tool | When to use | Command | |
||||
|
|------|-------------|---------| |
||||
|
| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` | |
||||
|
| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` | |
||||
|
| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` | |
||||
|
| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` | |
||||
|
| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` | |
||||
|
| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` | |
||||
|
|
||||
|
## Impact Risk Levels |
||||
|
|
||||
|
| Depth | Meaning | Action | |
||||
|
|-------|---------|--------| |
||||
|
| d=1 | WILL BREAK — direct callers/importers | MUST update these | |
||||
|
| d=2 | LIKELY AFFECTED — indirect deps | Should test | |
||||
|
| d=3 | MAY NEED TESTING — transitive | Test if critical path | |
||||
|
|
||||
|
## Resources |
||||
|
|
||||
|
| Resource | Use for | |
||||
|
|----------|---------| |
||||
|
| `gitnexus://repo/Build_God/context` | Codebase overview, check index freshness | |
||||
|
| `gitnexus://repo/Build_God/clusters` | All functional areas | |
||||
|
| `gitnexus://repo/Build_God/processes` | All execution flows | |
||||
|
| `gitnexus://repo/Build_God/process/{name}` | Step-by-step execution trace | |
||||
|
|
||||
|
## Self-Check Before Finishing |
||||
|
|
||||
|
Before completing any code modification task, verify: |
||||
|
1. `gitnexus_impact` was run for all modified symbols |
||||
|
2. No HIGH/CRITICAL risk warnings were ignored |
||||
|
3. `gitnexus_detect_changes()` confirms changes match expected scope |
||||
|
4. All d=1 (WILL BREAK) dependents were updated |
||||
|
|
||||
|
## Keeping the Index Fresh |
||||
|
|
||||
|
After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it: |
||||
|
|
||||
|
```bash |
||||
|
npx gitnexus analyze |
||||
|
``` |
||||
|
|
||||
|
If the index previously included embeddings, preserve them by adding `--embeddings`: |
||||
|
|
||||
|
```bash |
||||
|
npx gitnexus analyze --embeddings |
||||
|
``` |
||||
|
|
||||
|
To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.** |
||||
|
|
||||
|
> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`. |
||||
|
|
||||
|
## CLI |
||||
|
|
||||
|
| Task | Read this skill file | |
||||
|
|------|---------------------| |
||||
|
| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` | |
||||
|
| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` | |
||||
|
| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` | |
||||
|
| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` | |
||||
|
| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` | |
||||
|
| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` | |
||||
|
|
||||
|
<!-- gitnexus:end --> |
||||
Loading…
Reference in new issue