From 3c576c8bbed067690cc5219c06a1815ca9e99736 Mon Sep 17 00:00:00 2001 From: abhigyantrumio Date: Fri, 6 Mar 2026 12:46:01 +0530 Subject: [PATCH] feat(ai-context): replace skill router with inline imperative instructions CLAUDE.md and AGENTS.md now contain direct enforcement instructions instead of a passive skill router table. Based on Vercel eval data showing skills are skipped 56% of the time, and industry research on effective AGENTS.md patterns from 2,500+ repos. Key changes: - Always/When/Never three-tier boundary structure - RFC 2119 language (MUST, NEVER) for critical rules - Exact tool commands with parameters inline - Self-check checklist forcing model to verify its own work - ~77 lines, well within the <150 line adherence threshold Skills are still installed as bonus depth for Claude Code's skill system. Co-Authored-By: Claude Opus 4.6 --- gitnexus/src/cli/ai-context.ts | 100 +++++++++++++++++++++++++-------- 1 file changed, 77 insertions(+), 23 deletions(-) diff --git a/gitnexus/src/cli/ai-context.ts b/gitnexus/src/cli/ai-context.ts index 298e25e958..e32676bfd2 100644 --- a/gitnexus/src/cli/ai-context.ts +++ b/gitnexus/src/cli/ai-context.ts @@ -28,38 +28,92 @@ const GITNEXUS_END_MARKER = ''; /** * Generate the full GitNexus context content. - * - * Design principles (learned from real agent behavior): - * - AGENTS.md is the ROUTER — it tells the agent WHICH skill to read - * - Skills contain the actual workflows — AGENTS.md does NOT duplicate them - * - Bold **IMPORTANT** block + "Skills — Read First" heading — agents skip soft suggestions - * - One-line quick start (read context resource) gives agents an entry point - * - Tools/Resources sections are labeled "Reference" — agents treat them as lookup, not workflow + * + * Design principles (learned from real agent behavior and industry research): + * - Inline critical workflows — skills are skipped 56% of the time (Vercel eval data) + * - Use RFC 2119 language (MUST, NEVER, ALWAYS) — models follow imperative rules + * - Three-tier boundaries (Always/When/Never) — proven to change model behavior + * - Keep under 120 lines — adherence degrades past 150 lines + * - Exact tool commands with parameters — vague directives get ignored + * - Self-review checklist — forces model to verify its own work */ function generateGitNexusContent(projectName: string, stats: RepoStats): string { return `${GITNEXUS_START_MARKER} -# GitNexus MCP +# GitNexus — Code Intelligence + +This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 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: ""})\` — find execution flows related to the issue +2. \`gitnexus_context({name: ""})\` — see all callers, callees, and process participation +3. \`READ gitnexus://repo/${projectName}/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 | -This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows). +## Resources -## Always Start Here +| Resource | Use for | +|----------|---------| +| \`gitnexus://repo/${projectName}/context\` | Codebase overview, check index freshness | +| \`gitnexus://repo/${projectName}/clusters\` | All functional areas | +| \`gitnexus://repo/${projectName}/processes\` | All execution flows | +| \`gitnexus://repo/${projectName}/process/{name}\` | Step-by-step execution trace | -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** +## Self-Check Before Finishing -> If step 1 warns the index is stale, run \`npx gitnexus analyze\` in the terminal first. +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 -## Skills +## 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\` | +- Re-index: \`npx gitnexus analyze\` +- Check freshness: \`npx gitnexus status\` +- Generate docs: \`npx gitnexus wiki\` ${GITNEXUS_END_MARKER}`; }