What Makes a Good Codebase Wiki

A codebase wiki is useful when a future agent or human can make a safer code change faster after reading it. It should explain what the code cannot say on its own: rationale, constraints, cross-file flows, operational assumptions, failure modes, migrations, and external dependencies.

Sources#

Sources make a page trustworthy. A substantial page should show where its knowledge came from, and each source should say what it supports.

Use sources: for evidence:

sources:
  - id: capture-command
    type: file
    path: src/cli/commands/operations.ts
    note: Starts capture and records run metadata.
  - id: provider-docs
    type: web
    url: https://example.com/provider/docs
    retrieved_at: 2026-05-28
    note: Documents provider behavior used by this repo.

Use type: file for repo files, tests, migrations, prompts, and config. Use other source types for web docs, commits, PRs, conversations, wiki pages, or manual notes. Cite non-obvious claims with [@source-id] when the claim needs visible evidence.

Code is current truth for present-tense code claims. Conversations, old PRs, old commits, and incident notes are historical evidence unless the claim is verified against current code, tests, config, or current external docs.

Package updates should not rewrite wiki files. Mechanical migration of old source frontmatter should happen only through an explicit maintenance action such as almanac migrate legacy-sources.

Links#

Links make a page usable. Link concepts, not words. A good page links upward to the larger subject, sideways to adjacent systems, and downward to workflows, constraints, references, and source files.

Use readable link text in prose:

Capture updates pages through [[absorb-operation|the Absorb operation]].

Slug-only links are fine when the slug is already readable in context:

See [[capture-flow]].

Names#

Page names should be clear to a reader who has not seen the implementation. Prefer Claude Agent SDK, Capture Flow, and Where Almanac Stores Data over genre labels such as runtime-view or dependency-claude-agent-sdk.

Subject Neighborhoods#

A page is the unit of reading. A neighborhood is the unit of understanding. A large subject usually needs an anchor page plus nearby pages for behavior, structure, contracts, rationale, constraints, workflows, and sources.

Do not force every subject into every page shape. Small entities may need one page. Major subsystems and dependencies should grow into a linked neighborhood when one page becomes too dense.