kandev/docs/decisions/0001-file-based-knowledge-system.md

0001: File-based knowledge system

Status: accepted Date: 2026-03-28 Area: infra

Context

Agents working on Kandev had no way to record architectural decisions or store implementation plans for future reference. This led to repeated questions about "why was X done this way?" and lost context when features were revisited. The project needed a knowledge system that works across agent providers (Claude Code, Codex, Copilot) without custom infrastructure.

Decision

Use a three-tier, file-based knowledge system:

• Tier 1 (always loaded): CLAUDE.md stays slim and points to Tier 2 indexes.
• Tier 2 (index files): docs/decisions/INDEX.md and docs/plans/INDEX.md — one-line-per-entry tables that agents read to find relevant items.
• Tier 3 (individual files): Individual ADRs (docs/decisions/NNNN-*.md) and plans (docs/plans/YYYY-MM-*.md), loaded only when needed.

Architecture decisions are recorded as ADRs (this file is an example). Implementation plans are committed to docs/plans/ as permanent records after features are implemented.

A /record skill provides convenience for creating ADRs and plans, but the system works without it — agents can create files directly following the conventions.

Consequences

• Agents can discover past decisions by reading a small index file, then drill into specific ADRs.
• No file grows unbounded — each decision is its own file.
• Knowledge is committed to git and survives across sessions, branches, and agent providers.
• The /feature skill integrates with the decision log (reads in Phase 2, writes in Phase 6).
• Requires discipline to record decisions — this is a convention, not an enforcement mechanism.

Alternatives Considered

• Database-backed memory (SQLite, vector search): Too complex, requires infrastructure, doesn't work for agents that only read files.
• Append-only daily logs (OpenClaw pattern): Good for persistent agents but Kandev agents are session-scoped — daily logs would accumulate noise.
• Auto-compaction system: Not needed — the tiered index approach prevents unbounded growth in the first place.
• CLAUDE.md inline decisions: Would make CLAUDE.md grow unbounded and overwhelm agent context.