context-tree

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Context Tree Builder

**The committed, verified, team-shared knowledge layer for a brownfield codebase**

## What Context Tree Is

Context Tree is documentation-as-code for AI assistants working in brownfield repositories. It's a hierarchy of CLAUDE.md files that mirrors your source tree, plus a small set of conditionally-generated reference docs (GLOSSARY, ARCHITECTURE, BUSINESS_CONTEXT). Every claim is verified against actual code. Everything is committed to git, reviewed in PRs, and shared with the team.

- **Primary audience:** Claude Code (the AI). Senior developers can read it; Claude is the primary reader.
- **Scope:** The repo. Committed, team-shared, version-controlled.
- **Discipline:** Verified against code, not docs. Bad context is worse than bad code.
- **Origin:** Domain expert interviews + code verification + Rule-of-Two capture during everyday work.

## Relationship to Claude Code's Auto-Memory

As of Claude Code v2.1.59+, Anthropic ships an **auto-memory** feature — Claude observes corrections during your sessions and writes typed notes to `~/.claude/projects/<proj>/memory/`. That's a personal, machine-local layer.

**Context Tree is the committed, verified, team-shared layer.** They are complementary:

| | Auto-memory | Context Tree |
|---|---|---|
| Author | Claude (passive) | Human + Claude (active discipline) |
| Verification | None | Required against code |
| Scope | Your machine, per project | Repo (committed, team-shared) |
| Content | What Claude learned about *you* | What's true about *this codebase* |
| Lives in | `~/.claude/projects/<proj>/memory/` | `CLAUDE.md` + `docs/` in your repo |

Context Tree treats auto-memory as a **read-only signal source**. The `memory-promoter` skill (v4.0.0+) scans your local memory directory for entries whose content belongs in the committed tree, verifies them against code, and offers to promote them. Auto-memory is your personal scratchpad; Context Tree is the team's shared knowledge.

See [RELATIONSHIP_TO_MEMORY.md](https://github.com/RossH3/context-tree/blob/HEAD/RELATIONSHIP_TO_MEMORY.md) for the full mapping and decision flow.

### What Context Tree Is Not

- ❌ A replacement for auto-memory (it's not — auto-memory is great at what it does)
- ❌ Generic AI documentation methodology
- ❌ Tool-agnostic
- ❌ Greenfield project guidance

**We focus all energy on making Claude Code work better with YOUR brownfield codebase.**

---

This tool helps AI assistants understand legacy codebases by combining automated discovery with structured interviews of domain experts. The result is high-signal documentation that captures institutional knowledge AI can't infer from code alone.

## The Problem

AI assistants can explore code structure, but they can't know:
- Why architectural decisions were made
- What business terms mean (and how UI → code → DB terms map)
- What mistakes developers repeatedly make
- What takes longest to explain to new team members
- Institutional knowledge that exists only in people's heads

**Solution:** Automated discovery + domain expert interview + quality-gated documentation

---

## Quick Start

### Prerequisites
- Claude Code (or compatible AI assistant with slash command support)
- Access to someone who knows the codebase intimately (for interview phase)
- Brownfield codebase you want to document

### Installation

#### Claude Code Plugin

Install via Claude Code's plugin marketplace:

```bash
# In Claude Code
/plugin marketplace add RossH3/context-tree
/plugin install context-tree
/plugin list   # Verify install (see note below)
```

**Note on `/plugin list`:** Right after install, the first `/plugin list` may return empty output (Claude Code caching quirk, not plugin-specific). Run it a second time and the plugin appears. If you see "Run /reload-plugins to apply" after install, do that first.

**Update plugin:**
```bash
/plugin update context-tree
/reload-plugins   # Apply the update
```

**V4 Features:**
- **3 commands:** `/build-context-tree`, `/maintain-context-tree`, `/ingest-context`
- **5 composable skills:** `rule-of-two-detector`, `drift-detector`, `tree-health`, `learning-capture`, `memory-promoter`
- **Memory promotion:** Read auto-memory entries, verify against code, promote to committed tree (NEW in v4)
- **Multi-source ingestion:** Process post-mortems, Slack exports, meeting notes into verified docs
- **Frontmatter convention:** Generated docs carry typed frontmatter (aligned with auto-memory shape)
- **Knowledge.yaml routing:** Optional KCP-style manifest for trees with enough docs to need routing
- **Markdown working files** (no JSON artifacts)

This installs:
- Commands: Build workflow + maintenance orchestrator + multi-source ingestion
- Skills: Each maintenance mode is now its own skill, plus the new memory-promoter
- Workflow prompts: 3-phase build prompts + source ingestion prompt (markdown-based)
- Supporting scripts: git-learning-detector.sh

### Usage

Start Claude Code and run:
```bash
/build-context-tree
```

---

## How It Works

### Three-Phase Orchestrated Workflow

**Phase 1: Codebase Discovery (15-20 min)**
- Automated exploration of codebase using AI
- Identifies tech stack, architecture patterns, terminology traps
- Finds confusing areas to ask about in interview
- Output: `docs/context-tree-build/discovery.md` (human-readable markdown)

**Phase 2: Domain Expert Interview (30-60 min) ⭐ THE KEY DIFFERENTIATOR**
- Interactive Q&A with someone who knows the codebase
- One question at a time, adaptive based on answers
- Verifies answers against actual code immediately
- Captures institutional knowledge that code can't show
- Resumable across multiple sessions via summary section
- Output: `docs/context-tree-build/interview.md` (append-only markdown)

**Phase 3: Documentation Generation (30-45 min)**
- Generates docs from discovery + interview insights
- **Quality gates:** Only generates docs with ≥3 substantial insights
- **No generic slop:** If we don't have good content, we don't generate the doc
- Output: CLAUDE.md (always) + optional GLOSSARY.md, ARCHITECTURE.md, BUSINESS_CONTEXT.md

---

## What You Get

### Always Generated

**`CLAUDE.md`** - Navigation hub (~200 lines)
- Critical concepts (top 5 confusion points)
- Decision trees ("What are you trying to do?")
- Common pitfalls to avoid
- Quick reference for terminology and architecture

### Conditionally Generated (quality-gated)

**`docs/GLOSSARY.md`** - Only if ≥3 verified terminology mappings
- UI term → Code term → DB term mappings
- Why naming differences exist
- Search cheat sheet ("Looking for X? Grep for Y")

**`docs/ARCHITECTURE.md`** - Only if ≥3 non-obvious patterns
- Critical architectural patterns (multi-tenancy, dual databases, etc.)
- Why patterns exist (historical context, constraints)
- What breaks if violated
- Security-critical rules

**`docs/BUSINESS_CONTEXT.md`** - Only if ≥3 business insights
- What the system does and why
- Primary user workflows
- Business rules and domain concepts
- User roles and permissions

---

## Key Features

### Resumable Workflow
Each phase creates checkpoint files. If interrupted:
- Phase 1: Can skip or re-run if `discovery_summary.json` exists
- Phase 2: Continues from where you left off if `interview_notes.json` exists
- Phase 3: Can skip or regenerate if final docs exist

**Perfect for multi-session builds across days or weeks.**

### Quality Gates Prevent Generic Slop
Phase 3 only generates docs that have ≥3 substantial, verified insights.

**Better to have no GLOSSARY.md than one filled with obvious mappings.**

### Verification Built-In
- Phase 1: Checks actual code, not docs
- Phase 2: Verifies interview answers against code immediately
- Phase 3: Cross-checks all claims before writing docs

**Every architectural claim has file:line references.**

### Interactive Interview (The Unique Value)
Phase 2 asks domain experts focused questions one at a time:
- Adaptive: Follow-up questions based on answers
- Verified: Checks answers against code before accepting
- Resumable: Save progress after each Q&A
- Focused: Categories ensure comprehensive coverage

**This captures knowledge that would otherwise be lost.**

---

## Example Output

See [AI_DOCUMENTATION_FIELD_GUIDE.md](https://github.com/RossH3/context-tree/blob/HEAD/AI_DOCUMENTATION_FIELD_GUIDE.md) Part 5 for a real example from a production multi-tenant SaaS application.

**Notice:**
- Critical concepts up front (terminology traps, architecture gotchas)
- Decision trees for common tasks
- Minimal explanation, maximum navigation
- Under 200 lines total

---

## Usage Patterns

### For New Projects
1. Run `/build-context-tree` during onboarding
2. Complete all 3 phases in 1-2 sessions (90-120 minutes total)
3. Use docs during first week to validate effectiveness
4. Add incremental insights as needed

### For Existing Projects
1. Run Phase 1 & 2 to capture current state
2. Phase 3 generates baseline docs
3. Use [incremental capture pattern](https://github.com/RossH3/context-tree/blob/HEAD/AI_DOCUMENTATION_FIELD_GUIDE.md#part-2-incremental-capture-system) going forward
4. Update docs when you hit friction twice

### For Team Onboarding
1. Experienced developer runs interview (Phase 2 interviewee)
2. New developer reads generated docs
3. Track what's missing during first week
4. Update docs to fill gaps

---

## When NOT to Use This

**Don't use context-tree-builder if:**
- Codebase is small (< 1000 lines) - just read it
- Code is well-documented already - no need
- No domain expert available - Phase 2 is the key value
- Greenfield project - use conventional documentation

**Use this for:**
- Brownfield legacy codebases (5K+ lines)
- Complex domain logic not obvious from code
- Multi-tenant, multi-database, or unusual architectures
- Projects with terminology traps (UI ≠ code ≠ DB terms)
- When onboarding new developers repeatedly

---

## Core Principles

From 6 months of real-world usage:

1. **Verify against code, not docs** - Documentation lies, code doesn't
2. **Signal-to-noise ratio** - Every line must justify token cost
3. **No generic slop** - Only document what AI can't easily infer
4. **Quality over quantity** - Better no doc than bad doc
5. **Resumable** - Can stop and continue at checkpoint boundaries
6. **Focus on institutional knowledge** - The domain expert interview is the unique value

See [AI_DOCUMENTATION_FIELD_GUIDE.md](https://github.com/RossH3/context-tree/blob/HEAD/AI_DOCUMENTATION_FIELD_GUIDE.md) for deeper exploration.

---

## Files in This Repository

**Plugin (what gets installed):**
- `plugins/context-tree/commands/` — 3 commands: `build-context-tree`, `maintain-context-tree`, `ingest-context`
- `plugins/context-tree/skills/` — 5 skills: `rule-of-two-detector`, `drift-detector`, `tree-health`, `learning-capture`, `memory-promoter`
- `plugins/context-tree/docs/workflow-prompts/` — 4 subagent prompts (codebase-discovery, domain-interview, doc-generator, source-ingestion)
- `plugins/context-tree/git-learning-detector.sh` — Utility script for Rule of Two detection

**Marketplace manifest (for sharing):**
- `.claude-plugin/marketplace.json` — Repo-level manifest so teams can add this repo as a Claude Code marketplace

**Reference Documentation:**
- `RELATIONSHIP_TO_MEMORY.md` — How Context Tree relates to Anthropic auto-memory ⭐ START HERE
- `AI_DOCUMENTATION_FIELD_GUIDE.md` — Practical lessons and examples
- `CONTEXT_TREE_PRINCIPLES.md` — Deep dive on signal-to-noise, verification discipline
- `CHANGELOG.md` — Version history (v4 manifesto entry at top)

**Historical (Preserved for Learning):**
- `historical/` — Approaches that didn't scale, kept for context

---

## After Initial Build

After generating docs with `/build-context-tree`, three tools keep your Context Tree alive:

### Ingest External Sources

```bash
/ingest-context
```

Process post-mortems, Slack exports, meeting notes, or any document. Each insight is verified against code before being added. Contradicted claims are rejected. Nothing gets in without your approval.

### Structured Maintenance

```bash
/maintain-context-tree
```

**Five options:**
1. **Git Learning Analysis** - Detect repeated patterns from git history (Rule of Two violations)
2. **Quality Audit** - Validate claims against code, prune stale content
3. **Health Check** - Quick validation of links, structure, file sizes
4. **Learning Review** - Harvest undocumented learnings from recent git commits
5. **All** - Run options 1-4 in sequence (monthly maintenance)

### Proactive Capture (Automatic)

During normal work, when you and Claude produce a non-obvious synthesis (tracing a bug through multiple files, discovering how subsystems interact), Claude offers to capture it:

```
I traced this through 4 files -- this interaction isn't documented.
Want me to file it into ARCHITECTURE.md? (y/n)
```

Lightweight, easy to dismiss, ensures valuable insights don't evaporate into chat history.

### Natural Capture

**Just talk to Claude naturally:**
```
You: "I just figured out webhooks use HMAC auth, not bearer tokens. Let's document this."

Claude: [Verifies code, suggests CLAUDE.md section, shows draft, applies if approved]
```

No special command needed - Rule of Two principles guide natural interaction.

### Rule of Two
- **First time:** Just correct the mistake
- **Second time:** Document it (2-3 lines in CLAUDE.md)
- **Third time:** Prevented

See [AI_DOCUMENTATION_FIELD_GUIDE.md](https://github.com/RossH3/context-tree/blob/HEAD/AI_DOCUMENTATION_FIELD_GUIDE.md) for deeper exploration

---

## Utilities

### Git Learning Detector

**Analyzes git history to detect "Rule of Two" violations** - patterns indicating documentation opportunities.

The git-learning-detector identifies when the same issue appears twice in commit history, signaling it's time to document before the third occurrence.

#### What It Detects

1. **Repeated fix patterns** - Same issue fixed in different files (Common Pitfalls candidates)
2. **Defensive comments** - IMPORTANT/DON'T/NEVER added to code (pain signals)
3. **High churn files** - Files changed repeatedly (confusion zones)
4. **Terminology inconsistencies** - Multiple names for same concept (GLOSSARY candidates)
5. **Learning signals** - Commits with "TIL", "learned", "figured out", "gotcha"

#### Usage

```bash
# Download and run standalone
curl -sSL https://raw.githubusercontent.com/RossH3/context-tree/main/git-learning-detector.sh | bash

# Or clone and run locally
./git-learning-detector.sh [options]

# Options
./git-learning-detector.sh --since=6.months  # Analyze last 6 months
./git-learning-detector.sh --help            # Show all options
```

#### Output Example

```
=== GIT LEARNING DETECTOR ===

1. REPEATED FIX PATTERNS
  [3x] add clientid filter
  [2x] handle null organization

  → Suggestion: Add to CLAUDE.md Common Pitfalls
  Format: ❌ DON'T [common mistake] / ✅ DO [correct approach]

2. DEFENSIVE COMMENTS ADDED
  Found 15 defensive comments. Examples:
    + // IMPORTANT: All queries must include tenantid filter
    + // DON'T refactor InternalAuthPlugin - shared dependency

  → Suggestion: Review these warnings and add to CLAUDE.md

3. HIGH CHURN FILES
  12 changes: app/services/CoreService.java
   8 changes: app/controllers/EntryController.java

  → Suggestion: High churn indicates confusion - document patterns

4. TERMINOLOGY INCONSISTENCIES
  Organization ID variations:
    127x orgId
     34x org_id
     12x organizationId

  → Suggestion: Add to docs/GLOSSARY.md with preferred naming
```

#### Integration with Maintenance Workflow

Run monthly as part of context tree maintenance:

1. `./git-learning-detector.sh --since=1.month`
2. Review detected patterns (frequency ≥ 2)
3. Verify against code
4. Add 2-3 lines to appropriate location (CLAUDE.md, GLOSSARY.md, etc.)
5. Commit: `docs: capture learning from git history`

**This creates a feedback loop:** Git history reveals what developers struggle with → Document it → Struggles decrease → Signal-to-noise ratio improves.

---

## Contributing

This tool emerged from 6 months of experimentation on production codebases. The methodology evolved from comprehensive upfront documentation to this leaner orchestrated approach.

**Feedback welcome:**
- What worked for your codebase?
- What didn't work?
- What quality gates would you change?

Open an issue or PR.

---

## License

MIT License - See LICENSE file

---

## Credits

**Lessons learned from:** 6 months of production usage on multi-tenant SaaS applications

**Author:** Ross Hanahan

---

**Start here:** Read [AI_DOCUMENTATION_FIELD_GUIDE.md](https://github.com/RossH3/context-tree/blob/HEAD/AI_DOCUMENTATION_FIELD_GUIDE.md), then run `/build-context-tree`

Context Tree Builder

The committed, verified, team-shared knowledge layer for a brownfield codebase

What Context Tree Is

Context Tree is documentation-as-code for AI assistants working in brownfield repositories. It's a hierarchy of CLAUDE.md files that mirrors your source tree, plus a small set of conditionally-generated reference docs (GLOSSARY, ARCHITECTURE, BUSINESS_CONTEXT). Every claim is verified against actual code. Everything is committed to git, reviewed in PRs, and shared with the team.

Primary audience: Claude Code (the AI). Senior developers can read it; Claude is the primary reader.
Scope: The repo. Committed, team-shared, version-controlled.
Discipline: Verified against code, not docs. Bad context is worse than bad code.
Origin: Domain expert interviews + code verification + Rule-of-Two capture during everyday work.

Relationship to Claude Code's Auto-Memory

As of Claude Code v2.1.59+, Anthropic ships an auto-memory feature — Claude observes corrections during your sessions and writes typed notes to ~/.claude/projects/<proj>/memory/. That's a personal, machine-local layer.

Context Tree is the committed, verified, team-shared layer. They are complementary:

	Auto-memory	Context Tree
Author	Claude (passive)	Human + Claude (active discipline)
Verification	None	Required against code
Scope	Your machine, per project	Repo (committed, team-shared)
Content	What Claude learned about you	What's true about this codebase
Lives in	`~/.claude/projects/<proj>/memory/`	`CLAUDE.md` + `docs/` in your repo

Context Tree treats auto-memory as a read-only signal source. The memory-promoter skill (v4.0.0+) scans your local memory directory for entries whose content belongs in the committed tree, verifies them against code, and offers to promote them. Auto-memory is your personal scratchpad; Context Tree is the team's shared knowledge.

See RELATIONSHIP_TO_MEMORY.md for the full mapping and decision flow.

What Context Tree Is Not

❌ A replacement for auto-memory (it's not — auto-memory is great at what it does)
❌ Generic AI documentation methodology
❌ Tool-agnostic
❌ Greenfield project guidance

We focus all energy on making Claude Code work better with YOUR brownfield codebase.

This tool helps AI assistants understand legacy codebases by combining automated discovery with structured interviews of domain experts. The result is high-signal documentation that captures institutional knowledge AI can't infer from code alone.

The Problem

AI assistants can explore code structure, but they can't know:

Why architectural decisions were made
What business terms mean (and how UI → code → DB terms map)
What mistakes developers repeatedly make
What takes longest to explain to new team members
Institutional knowledge that exists only in people's heads

Solution: Automated discovery + domain expert interview + quality-gated documentation

Quick Start

Prerequisites

Claude Code (or compatible AI assistant with slash command support)
Access to someone who knows the codebase intimately (for interview phase)
Brownfield codebase you want to document

Installation

Claude Code Plugin

Install via Claude Code's plugin marketplace:

# In Claude Code
/plugin marketplace add RossH3/context-tree
/plugin install context-tree
/plugin list   # Verify install (see note below)

Note on /plugin list: Right after install, the first /plugin list may return empty output (Claude Code caching quirk, not plugin-specific). Run it a second time and the plugin appears. If you see "Run /reload-plugins to apply" after install, do that first.

Update plugin:

/plugin update context-tree
/reload-plugins   # Apply the update

V4 Features:

3 commands: /build-context-tree, /maintain-context-tree, /ingest-context
5 composable skills: rule-of-two-detector, drift-detector, tree-health, learning-capture, memory-promoter
Memory promotion: Read auto-memory entries, verify against code, promote to committed tree (NEW in v4)
Multi-source ingestion: Process post-mortems, Slack exports, meeting notes into verified docs
Frontmatter convention: Generated docs carry typed frontmatter (aligned with auto-memory shape)
Knowledge.yaml routing: Optional KCP-style manifest for trees with enough docs to need routing
Markdown working files (no JSON artifacts)

This installs:

Commands: Build workflow + maintenance orchestrator + multi-source ingestion
Skills: Each maintenance mode is now its own skill, plus the new memory-promoter
Workflow prompts: 3-phase build prompts + source ingestion prompt (markdown-based)
Supporting scripts: git-learning-detector.sh

Usage

Start Claude Code and run:

/build-context-tree

How It Works

Three-Phase Orchestrated Workflow

Phase 1: Codebase Discovery (15-20 min)

Automated exploration of codebase using AI
Identifies tech stack, architecture patterns, terminology traps
Finds confusing areas to ask about in interview
Output: docs/context-tree-build/discovery.md (human-readable markdown)

Phase 2: Domain Expert Interview (30-60 min) ⭐ THE KEY DIFFERENTIATOR

Interactive Q&A with someone who knows the codebase
One question at a time, adaptive based on answers
Verifies answers against actual code immediately
Captures institutional knowledge that code can't show
Resumable across multiple sessions via summary section
Output: docs/context-tree-build/interview.md (append-only markdown)

Phase 3: Documentation Generation (30-45 min)

Generates docs from discovery + interview insights
Quality gates: Only generates docs with ≥3 substantial insights
No generic slop: If we don't have good content, we don't generate the doc
Output: CLAUDE.md (always) + optional GLOSSARY.md, ARCHITECTURE.md, BUSINESS_CONTEXT.md

What You Get

Always Generated

CLAUDE.md - Navigation hub (~200 lines)

Critical concepts (top 5 confusion points)
Decision trees ("What are you trying to do?")
Common pitfalls to avoid
Quick reference for terminology and architecture

Conditionally Generated (quality-gated)

docs/GLOSSARY.md - Only if ≥3 verified terminology mappings

UI term → Code term → DB term mappings
Why naming differences exist
Search cheat sheet ("Looking for X? Grep for Y")

docs/ARCHITECTURE.md - Only if ≥3 non-obvious patterns

Critical architectural patterns (multi-tenancy, dual databases, etc.)
Why patterns exist (historical context, constraints)
What breaks if violated
Security-critical rules

docs/BUSINESS_CONTEXT.md - Only if ≥3 business insights

What the system does and why
Primary user workflows
Business rules and domain concepts
User roles and permissions

Key Features

Resumable Workflow

Each phase creates checkpoint files. If interrupted:

Phase 1: Can skip or re-run if discovery_summary.json exists
Phase 2: Continues from where you left off if interview_notes.json exists
Phase 3: Can skip or regenerate if final docs exist

Perfect for multi-session builds across days or weeks.

Quality Gates Prevent Generic Slop

Phase 3 only generates docs that have ≥3 substantial, verified insights.

Better to have no GLOSSARY.md than one filled with obvious mappings.

Verification Built-In

Phase 1: Checks actual code, not docs
Phase 2: Verifies interview answers against code immediately
Phase 3: Cross-checks all claims before writing docs

Every architectural claim has file:line references.

Interactive Interview (The Unique Value)

Phase 2 asks domain experts focused questions one at a time:

Adaptive: Follow-up questions based on answers
Verified: Checks answers against code before accepting
Resumable: Save progress after each Q&A
Focused: Categories ensure comprehensive coverage

This captures knowledge that would otherwise be lost.

Example Output

See AI_DOCUMENTATION_FIELD_GUIDE.md Part 5 for a real example from a production multi-tenant SaaS application.

Notice:

Critical concepts up front (terminology traps, architecture gotchas)
Decision trees for common tasks
Minimal explanation, maximum navigation
Under 200 lines total

Usage Patterns

For New Projects

Run /build-context-tree during onboarding
Complete all 3 phases in 1-2 sessions (90-120 minutes total)
Use docs during first week to validate effectiveness
Add incremental insights as needed

For Existing Projects

Run Phase 1 & 2 to capture current state
Phase 3 generates baseline docs
Use incremental capture pattern going forward
Update docs when you hit friction twice

For Team Onboarding

Experienced developer runs interview (Phase 2 interviewee)
New developer reads generated docs
Track what's missing during first week
Update docs to fill gaps

When NOT to Use This

Don't use context-tree-builder if:

Codebase is small (< 1000 lines) - just read it
Code is well-documented already - no need
No domain expert available - Phase 2 is the key value
Greenfield project - use conventional documentation

Use this for:

Brownfield legacy codebases (5K+ lines)
Complex domain logic not obvious from code
Multi-tenant, multi-database, or unusual architectures
Projects with terminology traps (UI ≠ code ≠ DB terms)
When onboarding new developers repeatedly

Core Principles

From 6 months of real-world usage:

Verify against code, not docs - Documentation lies, code doesn't
Signal-to-noise ratio - Every line must justify token cost
No generic slop - Only document what AI can't easily infer
Quality over quantity - Better no doc than bad doc
Resumable - Can stop and continue at checkpoint boundaries
Focus on institutional knowledge - The domain expert interview is the unique value

See AI_DOCUMENTATION_FIELD_GUIDE.md for deeper exploration.

Files in This Repository

Plugin (what gets installed):

plugins/context-tree/commands/ — 3 commands: build-context-tree, maintain-context-tree, ingest-context
plugins/context-tree/skills/ — 5 skills: rule-of-two-detector, drift-detector, tree-health, learning-capture, memory-promoter
plugins/context-tree/docs/workflow-prompts/ — 4 subagent prompts (codebase-discovery, domain-interview, doc-generator, source-ingestion)
plugins/context-tree/git-learning-detector.sh — Utility script for Rule of Two detection

Marketplace manifest (for sharing):

.claude-plugin/marketplace.json — Repo-level manifest so teams can add this repo as a Claude Code marketplace

Reference Documentation:

RELATIONSHIP_TO_MEMORY.md — How Context Tree relates to Anthropic auto-memory ⭐ START HERE
AI_DOCUMENTATION_FIELD_GUIDE.md — Practical lessons and examples
CONTEXT_TREE_PRINCIPLES.md — Deep dive on signal-to-noise, verification discipline
CHANGELOG.md — Version history (v4 manifesto entry at top)

Historical (Preserved for Learning):

historical/ — Approaches that didn't scale, kept for context

After Initial Build

After generating docs with /build-context-tree, three tools keep your Context Tree alive:

Ingest External Sources

/ingest-context

Process post-mortems, Slack exports, meeting notes, or any document. Each insight is verified against code before being added. Contradicted claims are rejected. Nothing gets in without your approval.

Structured Maintenance

/maintain-context-tree

Five options:

Git Learning Analysis - Detect repeated patterns from git history (Rule of Two violations)
Quality Audit - Validate claims against code, prune stale content
Health Check - Quick validation of links, structure, file sizes
Learning Review - Harvest undocumented learnings from recent git commits
All - Run options 1-4 in sequence (monthly maintenance)

Proactive Capture (Automatic)

During normal work, when you and Claude produce a non-obvious synthesis (tracing a bug through multiple files, discovering how subsystems interact), Claude offers to capture it:

I traced this through 4 files -- this interaction isn't documented.
Want me to file it into ARCHITECTURE.md? (y/n)

Lightweight, easy to dismiss, ensures valuable insights don't evaporate into chat history.

Natural Capture

Just talk to Claude naturally:

You: "I just figured out webhooks use HMAC auth, not bearer tokens. Let's document this."

Claude: [Verifies code, suggests CLAUDE.md section, shows draft, applies if approved]

No special command needed - Rule of Two principles guide natural interaction.

Rule of Two

First time: Just correct the mistake
Second time: Document it (2-3 lines in CLAUDE.md)
Third time: Prevented

See AI_DOCUMENTATION_FIELD_GUIDE.md for deeper exploration

Utilities

Git Learning Detector

Analyzes git history to detect "Rule of Two" violations - patterns indicating documentation opportunities.

The git-learning-detector identifies when the same issue appears twice in commit history, signaling it's time to document before the third occurrence.

What It Detects

Repeated fix patterns - Same issue fixed in different files (Common Pitfalls candidates)
Defensive comments - IMPORTANT/DON'T/NEVER added to code (pain signals)
High churn files - Files changed repeatedly (confusion zones)
Terminology inconsistencies - Multiple names for same concept (GLOSSARY candidates)
Learning signals - Commits with "TIL", "learned", "figured out", "gotcha"

Usage

# Download and run standalone
curl -sSL https://raw.githubusercontent.com/RossH3/context-tree/main/git-learning-detector.sh | bash

# Or clone and run locally
./git-learning-detector.sh [options]

# Options
./git-learning-detector.sh --since=6.months  # Analyze last 6 months
./git-learning-detector.sh --help            # Show all options

Output Example

=== GIT LEARNING DETECTOR ===

1. REPEATED FIX PATTERNS
  [3x] add clientid filter
  [2x] handle null organization

  → Suggestion: Add to CLAUDE.md Common Pitfalls
  Format: ❌ DON'T [common mistake] / ✅ DO [correct approach]

2. DEFENSIVE COMMENTS ADDED
  Found 15 defensive comments. Examples:
    + // IMPORTANT: All queries must include tenantid filter
    + // DON'T refactor InternalAuthPlugin - shared dependency

  → Suggestion: Review these warnings and add to CLAUDE.md

3. HIGH CHURN FILES
  12 changes: app/services/CoreService.java
   8 changes: app/controllers/EntryController.java

  → Suggestion: High churn indicates confusion - document patterns

4. TERMINOLOGY INCONSISTENCIES
  Organization ID variations:
    127x orgId
     34x org_id
     12x organizationId

  → Suggestion: Add to docs/GLOSSARY.md with preferred naming

Integration with Maintenance Workflow

Run monthly as part of context tree maintenance:

./git-learning-detector.sh --since=1.month
Review detected patterns (frequency ≥ 2)
Verify against code
Add 2-3 lines to appropriate location (CLAUDE.md, GLOSSARY.md, etc.)
Commit: docs: capture learning from git history

This creates a feedback loop: Git history reveals what developers struggle with → Document it → Struggles decrease → Signal-to-noise ratio improves.

Contributing

This tool emerged from 6 months of experimentation on production codebases. The methodology evolved from comprehensive upfront documentation to this leaner orchestrated approach.

Feedback welcome:

What worked for your codebase?
What didn't work?
What quality gates would you change?

Open an issue or PR.

License

MIT License - See LICENSE file

Credits

Lessons learned from: 6 months of production usage on multi-tenant SaaS applications

Author: Ross Hanahan

Start here: Read AI_DOCUMENTATION_FIELD_GUIDE.md, then run /build-context-tree