Skip to content

README.md

Latest commit

 

History

History
116 lines (82 loc) · 3.57 KB

README.md

File metadata and controls

116 lines (82 loc) · 3.57 KB

Codebase Context Skill

A Claude Code skill that generates lean context documents for AI agents, with automatic staleness detection.

What It Does

Creates pre-built context files so agents understand your codebase without blind exploration:

File Purpose Format
codebase-context.md Human-readable project overview (80-150 lines) Markdown
code-index.json Fast lookups for concepts, exports, types JSON
deps.mermaid Dependency graph for tracing imports Mermaid

Installation

git clone https://github.com/airowe/codebase-context-skill ~/.claude/skills/codebase-context

Usage

Generate context files

# Generate all machine-readable files (code-index.json, deps.mermaid, deps.json)
~/.claude/skills/codebase-context/scripts/generate-all.sh .

# Generate human-readable context via Claude
/codebase-context

Integrate with CLAUDE.md

Add one line to your project's CLAUDE.md:

For full project structure and workflows, see `.claude/codebase-context.md`.

That's it. The agent reads the context file when it needs to explore, skips it for targeted tasks.

Don't add a "CRITICAL: Read First" block — it forces the context to load on every request, wasting tokens on targeted tasks. See SKILL.md for details on why.

Generated Files

.claude/
├── codebase-context.md           # Human-readable context (80-150 lines)
├── code-index.json               # Machine-optimized lookups
├── deps.mermaid                  # Dependency graph (Mermaid)
├── codebase-context.snapshot     # Freshness snapshot
└── check-context-freshness.sh    # Freshness check script

Staleness Detection

.claude/check-context-freshness.sh

Detects:

  • Directory structure changes
  • Config file changes (package.json, tsconfig.json, etc.)
  • Age > 7 days

Best Practices

  1. Progressive disclosure — Reference context from CLAUDE.md, don't mandate preloading
  2. Keep it lean — Target 80-150 lines; over 200 means you should split content
  3. Concepts over file paths — Domain vocabulary is stable; file paths change constantly
  4. Monorepo structure — Use package-level CLAUDE.md for package-specific guidance
  5. Commit the files — Version control context, snapshot, and check script

What to include in context files

  • One-line project description
  • Directory tree (top 2-3 levels)
  • Domain concepts/vocabulary
  • Key workflows (1 line each)
  • Patterns and conventions
  • Gotchas

What to leave out

  • Environment variable examples (sensitive, discoverable from .env.example)
  • Code snippets / API usage examples (go stale, agent can read actual code)
  • Full file listings per screen/feature (too granular, changes frequently)
  • Deployment / App Store details (rarely relevant to coding tasks)
  • Marketing content

Scripts

Script Purpose Output
generate-all.sh Run all generators All files
generate-code-index.sh Extract concepts, exports, types, routes code-index.json
generate-deps.sh Build dependency graph deps.mermaid, deps.json

Supported languages: TypeScript/JavaScript, Python, Go (partial).

For best TypeScript/JavaScript results, install madge:

npm install -g madge

Example Output

License

MIT