CLAUDE.md Cross-Reference Loading Behavior

Details

Raw Data

{
  "id": "9cfb29a3-c608-4ab9-b2e5-fce4f1aa6420",
  "type": "general",
  "status": "completed",
  "title": "CLAUDE.md Cross-Reference Loading Behavior",
  "description": "Explaining how Claude handles cross-referenced files in CLAUDE.md",
  "context": {
    "output": "<div style=\"background:#1e1e1e;color:#e0e0e0;padding:20px;border-radius:8px;font-family:'Consolas','Monaco',monospace;\"><h2 style=\"font-family:sans-serif;color:#fff;margin:0 0 16px 0;\">CLAUDE.md Cross-Reference Loading</h2><h3 style=\"font-family:sans-serif;color:#61afef;margin:16px 0 12px 0;\">Short Answer: No</h3><p style=\"line-height:1.6;\">Cross-referenced files (like <code style=\"background:#2d2d2d;padding:2px 6px;border-radius:4px;color:#e5c07b;\">/gv/VIBE.md</code>, <code style=\"background:#2d2d2d;padding:2px 6px;border-radius:4px;color:#e5c07b;\">docs/KONTASK-GUIDE.md</code>, etc.) are <strong style=\"color:#e06c75;\">NOT automatically loaded</strong> when CLAUDE.md is read.</p><h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">How It Actually Works</h3><div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin:12px 0;\"><pre style=\"margin:0;line-height:1.8;\"><span style=\"color:#c678dd;font-weight:bold;\">1. Initial Load</span>\n   <span style=\"color:#7f848e;\">• Only CLAUDE.md content is injected into context</span>\n   <span style=\"color:#7f848e;\">• Links/references are just text pointers</span>\n\n<span style=\"color:#c678dd;font-weight:bold;\">2. When Claude Needs More</span>\n   <span style=\"color:#7f848e;\">• Claude must explicitly use Read tool</span>\n   <span style=\"color:#7f848e;\">• e.g., Read(\"/konnectvol/docs/KONTASK-GUIDE.md\")</span>\n\n<span style=\"color:#c678dd;font-weight:bold;\">3. Token Economy</span>\n   <span style=\"color:#7f848e;\">• Cross-references avoid bloating every turn</span>\n   <span style=\"color:#7f848e;\">• Claude reads files on-demand when relevant</span></pre></div><h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">Why This Design?</h3><table style=\"width:100%;border-collapse:collapse;margin:12px 0;\"><tr style=\"border-bottom:1px solid #3d3d3d;\"><td style=\"padding:8px 12px;color:#98c379;\">✓ Token Efficiency</td><td style=\"padding:8px 12px;color:#7f848e;\">CLAUDE.md alone is ~4K tokens; with all refs would be 20K+</td></tr><tr style=\"border-bottom:1px solid #3d3d3d;\"><td style=\"padding:8px 12px;color:#98c379;\">✓ Relevance</td><td style=\"padding:8px 12px;color:#7f848e;\">Only load what's needed for the current task</td></tr><tr style=\"border-bottom:1px solid #3d3d3d;\"><td style=\"padding:8px 12px;color:#98c379;\">✓ Freshness</td><td style=\"padding:8px 12px;color:#7f848e;\">Reading at runtime gets latest content</td></tr></table><h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">Cross-References in Your CLAUDE.md</h3><pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;color:#e0e0e0;\"><span style=\"color:#56b6c2;\">/gv/</span>\n├── <span style=\"color:#e5c07b;\">VIBE.md</span>                    <span style=\"color:#7f848e;\"># Vibe coding guide</span>\n├── <span style=\"color:#e5c07b;\">gvBUILD.md</span>                 <span style=\"color:#7f848e;\"># Current build plan</span>\n└── <span style=\"color:#56b6c2;\">docs/</span>\n    ├── <span style=\"color:#e5c07b;\">gvCodingStandards.md</span>   <span style=\"color:#7f848e;\"># Coding standards</span>\n    ├── <span style=\"color:#e5c07b;\">gvShellDesign.md</span>       <span style=\"color:#7f848e;\"># Product design</span>\n    └── <span style=\"color:#e5c07b;\">gvConnectionDesign.md</span>  <span style=\"color:#7f848e;\"># WebSocket architecture</span>\n\n<span style=\"color:#56b6c2;\">/konnectvol/</span>\n├── <span style=\"color:#e5c07b;\">CLAUDE-MAPPINGS.md</span>         <span style=\"color:#7f848e;\"># Code location mappings</span>\n└── <span style=\"color:#56b6c2;\">docs/</span>\n    ├── <span style=\"color:#e5c07b;\">KONTASK-GUIDE.md</span>       <span style=\"color:#7f848e;\"># Kontask UI templates</span>\n    └── <span style=\"color:#e5c07b;\">MERMAID-GUIDE.md</span>       <span style=\"color:#7f848e;\"># Diagram guide</span></pre><h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">Practical Implication</h3><p style=\"line-height:1.6;background:#2d2d2d;padding:12px 16px;border-radius:6px;\">When you mention something documented in a cross-referenced file (like \"use the kontask templates\"), I'll read that file to get the details. The references in CLAUDE.md serve as a <strong style=\"color:#98c379;\">roadmap</strong> telling me where to look—not pre-loaded content.</p></div>",
    "requestedAt": "2026-01-09T00:00:00.000Z",
    "requestId": "ae1813b8-0bdc-4afd-83a9-4b97b406a5a9",
    "choices": [
      {
        "label": "Pre-load key files",
        "value": "Let's discuss options for pre-loading the most important cross-referenced files into CLAUDE.md to reduce read operations",
        "primary": false
      },
      {
        "label": "Create summary file",
        "value": "Create a condensed summary file that combines the key points from all cross-referenced docs into one",
        "primary": false
      }
    ],
    "turnTiming": {
      "totalMs": 32768,
      "ttfeMs": 180,
      "thinkingMs": 32584,
      "toolExecutionMs": 0,
      "toolCallCount": 0,
      "thinkingPct": 99,
      "toolsPct": 0,
      "ttfePct": 1
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-08T14:15:38.795Z",
  "updatedAt": "2026-01-08T14:15:43.606Z",
  "requestId": "ae1813b8-0bdc-4afd-83a9-4b97b406a5a9",
  "scope": "vibetools",
  "tags": [
    "claude-code",
    "documentation"
  ],
  "targetUser": "claude"
}