3TKB — 3-Tier Knowledge Base

A framework for organizing project knowledge in three tiers, optimized for AI agent consumption.

1-index/          ← Master index — what exists and where (≤50 lines)
2-summaries/      ← One-page overviews per topic (≤2,000 chars)
3-descriptions/   ← Full specifications and details (≤50,000 chars)

Why?

AI coding agents (Claude Code, Cursor, Copilot, Codex) work best when they can quickly find relevant context. But projects grow, and a flat docs folder becomes a maze.

3TKB solves this with progressive disclosure:

1. Agent starts a session → reads Tier 1 (index + briefing) in 30 seconds
2. Agent identifies a topic → reads the relevant Tier 2 summary
3. Agent needs implementation detail → reads the Tier 3 spec

This minimizes token usage while ensuring agents always have the right context at the right depth.

Quick Start

# Scaffold a new knowledge base
npx @petter100/3tkb init my-kb

# Validate an existing knowledge base
npx @petter100/3tkb validate my-kb

Tier Rules

Tier 1 — Index (1-index/)

The entry point. Contains the master index and optionally an agent briefing.

• Max 50 lines per file
• Format: Topic | Description | [Link](path)
• Should link to every Tier 2 category

# My Project — Master Index
## Version: 1.0.0 | Last Updated: 2026-02-24

Product | Features, tech stack, roadmap | [2-summaries/product/](../2-summaries/product/)
Infrastructure | Hosting, CI/CD, monitoring | [2-summaries/infrastructure/](../2-summaries/infrastructure/)

Tier 2 — Summaries (2-summaries/)

One-page overviews organized by category. Read these for context before diving deeper.

• Max 2,000 characters per file
• Header format: # Title | vX.Y.Z | YYYY-MM-DD
• Organized into category subdirectories
• Should reference related Tier 3 files

Tier 3 — Descriptions (3-descriptions/)

Full specifications, detailed designs, and complete documentation.

• Max 50,000 characters per file
• Header format: # Title | vX.Y.Z | YYYY-MM-DD
• Mirrors Tier 2 category structure
• Contains code examples, data models, architecture diagrams

Assets (assets/)

Non-markdown files (PDFs, images, diagrams). Mirrors the tier folder structure.

Version Headers

Every markdown file (except README.md) must have a version header as the first line:

# My Document Title | v1.0.0 | 2026-02-24

Bump the version on every edit:

• Patch (1.0.0 → 1.0.1): Small fixes, typos
• Minor (1.0.0 → 1.1.0): Content additions, updates
• Major (1.0.0 → 2.0.0): Structural changes, rewrites

Validator

The CLI validator checks your knowledge base for compliance:

npx @petter100/3tkb validate [path]

What it checks

Check	Description
Size limits	Files within tier character/line limits
Version headers	Every .md file has # Title | vX.Y.Z | YYYY-MM-DD
Cross-references	Markdown links point to existing files
Orphaned directories	Summary directories referenced in index

CI Integration

# GitHub Actions
- name: Validate knowledge base
  run: npx @petter100/3tkb validate knowledge-base/

Exit code 1 on errors — fails the build if the KB is invalid.

AI Tool Integration

3TKB works with any AI coding tool. See the Integration Guide for setup with:

• Claude Code — CLAUDE.md files
• Cursor — .cursor/rules/ files
• GitHub Copilot / Codex — AGENTS.md files
• llms.txt — LLM-friendly documentation standard

Example

See examples/saas-startup/ for a complete worked example — a fictional project management SaaS with index, summaries, and a detailed feature spec.

Origin

3TKB was born from building ATR (All The Rest), a SaaS platform with 15+ knowledge categories across 4 apps. We needed a way for AI agents to quickly find relevant context without reading everything. The 3-tier pattern emerged naturally and proved effective across Claude Code, Cursor, and other tools.

License

MIT