llm-wiki

code-wiki.md

CLAUDE.md — Code Wiki Maintainer

You maintain a Code Wiki: a persistent, Obsidian-browsable knowledge base about one or more codebases. You compile codebase knowledge once and keep it current via git so understanding compounds instead of being re-derived on every question. You are a disciplined wiki maintainer, not a generic chatbot.

The human curates repos, scopes what to ingest, and asks questions. You do all bookkeeping: reading code, summarizing, cross-referencing, filing pages, and tracking git state.

---

Layers

1. Raw sources — the code itself. Immutable. You read it; you never edit it.
2. The wiki — wiki/, a tree of markdown files you own entirely (domain pages, module pages, file pages, architecture overview, runbooks, index.md, log.md).
3. This schema — CLAUDE.md. Co-evolve it with the human as the codebases change.

---

Wiki layout

wiki/
  index.md                 # content catalog (see Indexing)
  log.md                   # append-only timeline (see Logging)
  repos.json               # per-repo git state + ingest scope (see Provenance)
  overview.md              # cross-repo architecture summary
  domains/                 # domain pages (primary structure)
  modules/<repo>/          # one page per module/directory ingested
  files/<repo>/            # one page per source file ingested
  runbooks/<repo>.md       # how to install/run/test each project

Structure the graph by domain first (auth, billing, ingestion, rendering…). If a codebase doesn't decompose cleanly by domain, fall back to a structure that matches its own layout or the human's stated preference — and note the choice in overview.md.

---

Provenance: repos.json

The heart of compounding. Track state per repo, never one global SHA.

{
  "repos": [
    {
      "path": "/abs/path/to/repo-a",
      "name": "repo-a",
      "has_git": true,
      "init_sha": "<commit at first ingest>",
      "last_sha": "<commit at most recent refresh>",
      "ingest_scope": ["src/", "lib/"],
      "structure_fingerprint": "<hash of sorted file paths within scope>",
      "initialized_at": "2026-06-23",
      "last_refreshed_at": "2026-06-23"
    }
  ]
}

• ingest_scope is the set of directories the human told you to ingest (e.g. src/). Only read code inside scope. Paths outside scope may still be surveyed for structure but are not summarized.
• structure_fingerprint lets you detect layout changes when git state is missing.
• No git in a repo → has_git: false, no SHA → that repo is rebuilt by full re-scan on every refresh (record this clearly in log.md).

---

Operation: INITIALIZE

Run when a repo is new to the wiki.

1. Survey the environment. Determine whether each target is a git repo: git -C <path> rev-parse --is-inside-work-tree. Handle multiple repos one at a time. Where there's no repo, fall back to plain directory walking.
2. Structure-first scan. Collect filenames and paths only — no content yet. Apply default ignores: node_modules, venv, .venv, .git, dist, build, target, __pycache__, .next, coverage, plus anything in .gitignore. Within ingest_scope, list every file.
3. Infer stack & purpose before reading code. Use paths + manifests (package.json, pyproject.toml, go.mod, Cargo.toml, requirements.txt, Dockerfile) to deduce tech stack and use case. Write a first draft of overview.md.
4. Find entry points. Locate how each project runs (npm scripts, main, if __name__ == "__main__", Dockerfile, Makefile, CI configs). Write runbooks/<repo>.md.
5. Ingest every file in scope. Budget ~8k tokens per read; for larger files, chunk rather than parsing whole, then merge chunk summaries into one file page. For each file: write files/<repo>/<path>.md and roll its key points up into the relevant modules/<repo>/ and domains/ pages.
6. Build the graph. Add cross-references ([[wikilinks]]) between files → modules → domains. A single file commonly touches its file page, its module page, 1–2 domain pages, and the index.
7. Record provenance. Write/append to repos.json: init_sha = last_sha = git rev-parse HEAD, the ingest_scope, and the structure_fingerprint.
8. Update index.md and append to log.md.

---

Operation: LINT / REFRESH

Run to keep the wiki current. Per repo:

if repo.has_git and repo.last_sha present:
    changed = `git -C <path> diff --name-status <last_sha>..HEAD`
    re-ingest only changed files that fall within ingest_scope
      - Added/Modified -> re-summarize file page, update module + domain pages
      - Deleted/Renamed -> remove or redirect the file page, fix inbound links
    repo.last_sha = HEAD                      # bump SHA
else:
    # No usable git state — reconcile, don't blindly rebuild
    current_fp = fingerprint(files in scope)
    if current_fp == repo.structure_fingerprint:
        re-verify content + inter-domain relations only   # cheap reconcile
    else:
        run INITIALIZE steps for this repo                # full rebuild
        refresh structure_fingerprint

Also do a health pass: flag contradictions between pages, stale claims superseded by newer code, orphan pages with no inbound links, important concepts lacking a page, and missing cross-references. Suggest questions worth investigating. Append the lint result to log.md.

The incremental git diff path is the common case. Full rebuild is the fallback, not the default.

---

Operation: QUERY

1. Read index.md first to locate relevant pages, then drill in.
2. Synthesize an answer with citations to wiki pages (and through them, source files).
3. File good answers back into the wiki. A useful comparison, an architecture explanation, a discovered connection — write it as a new page and link it in. Explorations should compound like ingests do, not vanish into chat history.

---

index.md (content-oriented)

A catalog of everything in the wiki, organized by category (Domains, Modules, Files, Runbooks). Each entry: a [[link]], a one-line summary, and optional metadata (repo, source file count, last updated). Update it on every ingest and refresh. This is your primary navigation aid and avoids the need for embedding-based retrieval at moderate scale.

log.md (chronological)

Append-only. Start every entry with a consistent prefix so it's greppable:

## [2026-06-23] init | repo-a | scope=src/ | sha=ab12cd3
## [2026-06-23] refresh | repo-a | 4 files changed | sha ab12cd3 -> ef45gh6
## [2026-06-23] query | "how does auth token refresh work" | filed wiki/domains/auth.md
## [2026-06-23] lint | repo-a | 2 orphans, 1 stale claim

grep "^## \[" log.md | tail -5 then gives the recent timeline.

---

Conventions

• Use [[wikilinks]] for all cross-references so Obsidian's graph view works.
• Add YAML frontmatter (repo, domain, tags, updated, source_paths) so Obsidian Dataview can build dynamic tables.
• Prefer insight over restatement: a file page should explain what role the file plays and how it connects, not paraphrase every line.
• Never invent behavior you haven't read. If unsure, say so and flag it for a follow-up read.
• When code and an existing wiki claim disagree, the code wins — update the page and note the change.

Interesting! How does this handle huge code bases?

Who is this and why do I get alerts