Code Documentation & Navigation Guide

This skill provides a Codebase Knowledge Graph to help you navigate complex projects without reading thousands of files. It uses a local SQLite database to store file relationships, dependency layers, and symbol definitions.

⚠️ CRITICAL: BLOCKING REQUIREMENTS (触发条件)

STOP! READ THIS BEFORE PROCEEDING.

You MUST invoke this skill (code-doc-guid) as a BLOCKING STEP before performing any of the following actions. Failure to do so is a violation of protocol.

🔴 Mandatory Pre-Action Check (Recon Phase)

Trigger: You are about to:

• Modify any code file (Write, SearchReplace).
• Rename or move files (RunCommand: mv/ren).
• Delete files (DeleteFile).
• Refactor a class, function, or variable.

Action: You MUST run python ... codebase_manager.py inspect/search FIRST. Reason: You cannot safely modify code without knowing who depends on it. "Guessing" is strictly prohibited.

🟢 Mandatory Post-Action Sync (Archive Phase)

Trigger: You have just finished a set of file modifications. Action: You MUST run python ... codebase_manager.py update. Reason: The knowledge graph must remain consistent with the disk state for the next turn.

---

Workflow & Commands

All commands are run via python scripts/codebase_manager.py <command> [args]. (Note: If running manually, adjust the path to where you saved the script)

1. search - Find Symbols & Concepts

Use this to locate code by name or intent (docstring).

• Command: search <query>
• Example: search "UserAuth"
• Output: JSONL format containing file paths, symbol names, and docstrings.
• Action: Use this to find the exact file path before reading it.

2. inspect - Analyze Dependencies & Risk

Use this to understand the impact of a change.

• Command: inspect <filename_fragment>
• Example: inspect "auth_service"
• Output (JSON):
  • risk_score: HIGH / MEDIUM / LOW.
  • doc_file: Path to the detailed report (e.g., .trae/codeguiddoc.md).
• Action Guidelines:
  1. Read the JSON summary first.
  2. IF RISK IS HIGH:
     • STOP. Do not modify code yet.
     • READ the generated markdown file (doc_file). It contains a Mermaid Graph and full dependency list.
     • SHOW the Mermaid graph to the user (if possible) or summarize the impact: "This change affects 25 files, including core modules A and B."
     • ASK for confirmation.

3. update - Refresh Index

Use this after ANY file modification.

• Command: update
• Output: "Processing X changed files..."
• Note: It is incremental and very fast (<1s usually). Always run this before finishing your turn.

4. graph - Export Visuals (Optional)

Use this only when the user explicitly asks for an architecture overview.

• Command: graph
• Output: Generates .trae/architecture_layers.md (Human readable) and .trae/dependency_graph.json (Machine readable).

Token Economy Strategy

To save tokens and time:

1. Don't read whole files to find one function. Use search -> Read(limit=20, offset=N).
2. Don't guess dependencies. Use inspect to see the exact relationship graph.
3. Trust the Layering. If you are modifying a Layer 0 file, be extremely careful—it breaks everything. If modifying Layer 5, it's likely safe.