Documentation Practices / AI-Assisted Development
KALDAMUS — Jun 2026

Living memory for AI‑assisted projects

The case for PROJECT.mdCHANGELOG.mdsession logs — their concrete benefits, their real costs, and how this practice compares to emerging alternatives.

slides  ·  Use ← → to navigate  ·  number keys to jump
Living Documentation| / The Practice
kaldamus • doc practices • 2026
THE PROBLEM Each AI session starts with zero memory. Without shared documents, every session re-derives the same context and repeats the same mistakes — costing 20–40 min of orientation per session. PROJECT.md Indexed living spec · ~1700 lines ▸ §0 Quick index (2K tokens vs 48K full) ▸ 22 sections: goals, data model, LLM prompts ▸ invariants & non-goals prevent scope creep ▸ update obligation: stale §'s updated each session Audience AI agent orienting to the codebase Human architect reviewing scope New contributor understanding rules Load §0 first; read only the section(s) the task touches. CHANGELOG.md Append-only chronicle · newest first ▸ Date / Goal / Changes / Verify fields ▸ never edited; prepend-only discipline ▸ 3-month window tells "what changed lately" ▸ doubles as async standup for the team Audience AI agent scanning recent activity Team member catching up after absence Reviewer asking "what changed this sprint?" Immutability is the invariant — never edit past entries. Session Logs docs/SESSION_YYYY-MM-DD_slug.md ▸ Goals → Investigation → Plan → Impl ▸ → Verification → Tradeoffs → Follow-ups ▸ captures the reasoning chain, not just diffs ▸ answers "why did Alice do it this way?" Audience Future AI sessions replaying decisions Engineers asking why an approach was chosen Post-mortems tracing root causes Investigation section is the most valuable — what you tried. SESSION-END RITUAL (CLAUDE.md obligation — ~20 min, every session) ① Write session log docs/SESSION_YYYY-MM-DD_slug.md Use §22 house structure Goals → Impl → Verification → ② Prepend CHANGELOG Date / Goal / Changes / Verify Newest entry at top Never edit past entries → ③ Update PROJECT.md Mark stale §sections fresh Update only sections the session's changes touched

The core problem: LLMs have no memory across sessions. Without persistent context documents, each AI assistant session wastes 20–40 minutes re-orienting — re-reading files, re-deriving constraints, re-discovering decisions already made.

Three documents, three jobs: PROJECT.md is the indexed living spec (load §0 first, then only the relevant sections — 2K tokens instead of 48K). CHANGELOG.md is the append-only chronicle of what changed and why. Session logs capture the full reasoning chain — what was tried, what was rejected, and why the winning approach was chosen.

The session-end ritual is codified in CLAUDE.md as a three-step obligation: write the session log, prepend the CHANGELOG, and update any PROJECT.md sections the session's changes made stale. Takes ~20 minutes. Skipping it compounds as debt.

§0 is the efficiency win. The Quick index lets an AI agent load 2K tokens instead of 48K and still find any section by keyword. It's the difference between a grep and reading the whole file.
Living Documentation| / Assessment
kaldamus • doc practices • 2026
BENEFITS ✓ Orientation time: 20–40 min → under 5 min per session ✓ §13 invariants short-circuit scope debates in review ✓ Session logs answer "why?" without blame-blame archaeology ✓ CHANGELOG doubles as async standup (no meeting needed) ✓ New engineers productive in hours, not days These benefits compound: each session log reduces the cost of the next one by pre-answering "why?" questions before they arise. COSTS & RISKS ✗ ~20 min overhead per session if ritual is followed ✗ 1700-line PROJECT.md causes git merge conflicts at scale ✗ Section staleness if ritual is skipped (discipline dependency) ✗ Session log quality varies by author; low-effort logs mislead ✗ No automated enforcement — all social contract Mitigations: PR template checklist, section owners in §0, git MCP for navigation queries, ADRs for durable decisions. vs ALTERNATIVES Tool Covers Gaps ADRs durable decisions no investigation trail CLAUDE.md agent behavior rules not a knowledge base Git MCP what/when queries cannot answer "why not X" AI memory cross-session persistence provider-specific, opaque LLMWiki multi-author at scale setup cost; favors 50+ eng These tools are additive, not substitutes. ADRs + session logs + Git MCP is stronger than any one alone. LLMWiki replaces PROJECT.md when the file exceeds ~100 pages. WHEN TO ADOPT Day 1: CLAUDE.md + CHANGELOG Zero friction. Immediate benefit. Every AI-assisted project. CHANGELOG discipline is the highest-ROI starting point. Week 1–2: PROJECT.md §0 + session logs Add once orientation pain is felt. Structure §0 first. Session logs become valuable after 3–5 sessions of history. Month 2+: ADRs + section owners Add ADRs when decisions need permanence beyond a session. Assign §0 section owners once the team exceeds 4 people.

Benefits are real and measurable: orientation time drops from 20–40 minutes to under 5; invariants short-circuit review debates; session logs answer "why?" without archaeology; CHANGELOG replaces async standups.

Costs are mostly discipline costs: the ritual takes ~20 min, skipping it compounds as debt, and a 1700-line monolith develops merge conflicts as the team grows. None of these are blockers at small scale — they're scaling signals.

Alternatives are additive: ADRs capture durable decisions but lack investigation trails. Git MCP answers what/when but cannot recover reasoning never committed. AI memory is opaque and provider-specific. LLMWiki is worth adopting when PROJECT.md exceeds ~100 pages or the team passes ~50 engineers.

Start with CHANGELOG. It requires zero structure, provides immediate value (async standup, recent context for AI), and builds the discipline muscle the rest of the practice depends on.
/ ADRs in Depth
DOC PRACTICES · Kaldamus

Architecture Decision Records: the closest cousin

ADR FORMAT (Nygard, 2011) docs/decisions/0042-encoder-nli-classifier.md TITLE Use encoder NLI for classification STATUS Accepted Supersedes ADR-0031 CONTEXT Qwen LOGIT classifier scores 0.74 on n=300 GT; resource-heavy DECISION Switch to DeBERTa-v3-base NLI via zero-shot-classification CONSEQ. 0.8333 accuracy; 184M params vs 1500M; gated by classifier_backend Status chain (unique to ADRs) 0031-qwen-logit → superseded by 0042-encoder-nli → may be superseded by... No investigation section · No verification evidence No follow-ups · Per-decision, not per-session Lives in docs/decisions/ · Numbered sequentially adr-tools CLI can scaffold + link the chain SESSION LOG (kaldamus) Goals Verbatim user framing · distilled intent Investigation ✦ MLM verbalizer vs NLI vs embedding cosine benchmarked on n=190 GT — NLI wins 0.8368 ✦ absent from ADRs — reasoning chain lost Plan → Implementation classifier_nli.py · classifier_backend flag commit 1212dfb on main Verification ✦ 0.8333 encoder vs 0.7400 Qwen on n=300 reproduced through EvalPipeline end-to-end ✦ absent from ADRs — no evidence record Tradeoffs Accepted Default backend stays 'llm'; encoder gated Follow-ups Dependency eval entity · over-time coherence Per-session scope · includes reasoning + evidence No status chain · no supersession tracking
Michael Nygard, 2011 docs/decisions/ adr-tools

ADRs are intentionally narrow: one record per decision, lightweight enough that engineers actually write them. Their killer feature is the status chain — a decision can be Proposed, Accepted, Deprecated, or Superseded, and the superseding ADR links back. You can trace the full evolution of any architectural choice across months or years.

Session logs are intentionally broad: one record per session, capturing the investigation, alternatives tried, implementation, and verified evidence. The Investigation and Verification sections are what ADRs lack — you know what was decided but not what was measured or what was tried and rejected.

The two are complementary at different granularities. A good workflow: write session logs during development; when a decision proves durable (survives two or more sessions unchanged), promote it to an ADR with the status chain. Session logs are the raw material; ADRs are the distillate.

Key Insight

ADRs track decision evolution (status chain); session logs capture reasoning evidence. Both together are more complete than either alone.

/ MCP Over Git
DOC PRACTICES · Kaldamus

Could an MCP layer on git replace the documents?

mcp-server-git git log · git diff · git blame · git show · git grep WHAT MCP-OVER-GIT ANSWERS WELL “What changed in api/workers/ this week?” git log --since=7days -- api/workers/ “Who last touched classifier.py and why?” git blame + git show <sha> (commit message) “Find commits mentioning priority_score” git log --all --grep=priority_score “Diff between last week and today” git diff HEAD~7..HEAD -- api/ “What files changed most often?” git log --format='' --name-only | sort | uniq -c WHAT IT STILL CANNOT ANSWER “Why didn't we use the MLM verbalizer?” never committed — lives in SESSION_2026-06-04 “What was the perf baseline when we shipped?” numbers not structured in commits; in CHANGELOG “What invariants must I preserve?” scattered across code; indexed only in PROJECT.md §13 “What was considered and rejected?” no record — reasoning never reaches git history “What is the current shape of the system?” git log is a delta stream, not a snapshot spec MCP-git replaces CHANGELOG partially Navigation + archaeology queries are better answered by mcp-server-git than by a manually written log. Shorten CHANGELOG entries; don't remove them. Cannot replace PROJECT.md or session logs Reasoning that was never written is not in git. A delta stream can't substitute for a living spec. MCP-git is additive, not a substitute.
mcp-server-git github MCP semantic search

MCP-over-git is real and already deployed in tools like the official mcp-server-git and GitHub's own MCP server. They give an LLM structured access to the commit graph, file history, and diffs — without requiring the agent to shell out to git log manually.

The efficiency gain is real for archaeology and navigation: finding when a file changed, who touched it, or which commits mention a keyword. This directly reduces the value of a manually written CHANGELOG for those queries — git does it better and always stays up to date.

The hard limit is fundamental: git only stores what was committed. The reasoning chain, rejected alternatives, verified performance numbers, and system invariants were never in git to begin with. MCP-over-git provides a faster lookup into an incomplete record; it doesn't fill the gaps.

The right framing: adopt MCP-over-git alongside the three-document system. Let it handle "what changed when" so CHANGELOG entries can be shorter summaries. Keep PROJECT.md and session logs for the content that was never in git.

Key Insight

MCP-over-git answers the "what and when" half efficiently. It cannot answer the "why not X" half — that reasoning was never committed.

/ LLMWiki Concept
DOC PRACTICES · Kaldamus

LLMWiki: a wiki structured for LLM retrieval

PERSISTENT REFERENCE SESSION-AWARE / EPHEMERAL MANUAL CURATION AUTOMATED / AI-GEN MANUAL + PERSISTENT AUTO + PERSISTENT MANUAL + SESSION AUTO + SESSION PROJECT .md ADRs 0042 LLMWiki Notion AI Confluence AI Session Logs CHANGE LOG AI Mem mem0/Zep Git MCP README (stale) LLMWiki design principles Semantic chunking (not page-level) Cross-links for navigation Auto-summarization of stale pages Search replaces the §0 index §0 index = deterministic retrieval LLMWiki = probabilistic search
Notion AI Confluence AI Obsidian + LLM

An LLMWiki is a wiki structured for LLM retrieval: semantically chunked pages, cross-linked for navigation, with search as the primary access pattern (rather than a hand-crafted index). Notion AI, Confluence with AI features, and Obsidian with vector-search plugins are the closest real implementations.

It occupies the same quadrant as PROJECT.md on the map — persistent reference, manually curated — but adds two things PROJECT.md lacks: multi-author without merge conflicts, and search-based discovery that scales as the corpus grows past what a single index table can represent. At 8-person scale and beyond, those two properties matter a lot.

The tradeoff is retrieval reliability. The kaldamus §0 Quick index is deterministic: the reader is told exactly which section to load. An LLMWiki uses probabilistic search: the right chunk must surface in the top-k results. For small, well-defined codebases, deterministic beats probabilistic. For large or multi-team contexts, search is the only viable approach.

An LLMWiki does not help with session logs or CHANGELOG — it is a replacement path for PROJECT.md only, and only at scale.

Key Insight

LLMWiki replaces the §0 index with search. That trade is unfavorable for a solo project; it becomes favorable past ~8 engineers or ~100 wiki pages.

/ Team Scale
DOC PRACTICES · Kaldamus

At 8 people: what changes, what breaks, what to add

DOCUMENT EFFICIENCY GAINED COST IMPOSED MITIGATION PROJECT.md §0 index = team onboarding in minutes, not days Replaces onboarding calls §13 invariants = fewer review cycles on obvious violations Merge conflicts on 1700-line file Section ownership unclear Stale when owner changes role Split into per-section files Assign section owners in §0 Or migrate to LLMWiki CHANGELOG Async standup substitute; visibility across sub-teams Reduces Slack "what shipped?" PM can read verification entries instead of asking engineers Conflicts when 2+ PRs merge same day; blame unclear mcp-server-git overlaps it Add CHANGELOG update to PR template (CI check) Keep entries shorter; lean on MCP-git for nav Session Logs Cross-team reasoning capture; "why did Alice change this?" answered in docs/ Tradeoffs section replaces lengthy code-review comment threads about past decisions Follow-ups visible to whole team Quality variance: thorough vs bullet-point vs skipped entirely No one reads other people's logs unless forced Enforce template in CLAUDE.md Make logs required for PRs with architectural changes; optional for hotfixes. Graduate durable decisions to ADRs. The Ritual AI agents still own their own ritual Each engineer + their AI agent pair responsible for their session Culture-dependent; some engineers skip under deadline pressure PR checklist item: “session doc written or N/A (trivial fix)?” Net verdict at 8 people: practice scales reasonably with structural additions (PR template, section owners, MCP-git for CHANGELOG queries). It does not scale to 50 people without replacing session logs with ADRs and PROJECT.md with a proper LLMWiki.
8-person team merge conflicts PR templates

At 8 people, the practice delivers new efficiencies that solo use doesn't surface: the CHANGELOG becomes a genuine async standup substitute, and PROJECT.md §13 invariants reduce code-review back-and-forth on architectural violations. Session logs answer "why did Alice make this call?" without a synchronous conversation.

The costs are also new. Merge conflicts on a 1700-line PROJECT.md are a real friction source when two engineers work simultaneously. Quality variance in session logs — one person writes thorough Investigation sections, another writes bullet points, a third skips — means the corpus becomes unreliable as a team resource.

The mitigations are structural, not cultural: add the session doc as a PR template checklist item (required for architectural changes, N/A for hotfixes); assign section owners in §0; consider splitting PROJECT.md into per-section files to reduce conflict surface; let MCP-over-git handle the "what changed when" queries that CHANGELOG currently serves.

The tipping point to an LLMWiki for PROJECT.md is around 50 engineers or 100+ sections — not at 8, where the deterministic §0 index still beats probabilistic search.

Key Insight

At 8 people, the three documents scale — with PR-template enforcement and section owners. Past ~50, replace PROJECT.md with an LLMWiki and session logs with ADRs.

/ Proposal
DOC PRACTICES · Kaldamus

Adopting this in a brownfield repo

EXISTING GIT REPO history + source, but no PROJECT.md · no CHANGELOG.md · no session-docs/ ↓ ① GENERATE PROJECT.md ▸ Point an AI agent at the repo ▸ Crawl src tree → modules, data model ▸ Mine git log → churn = core modules ▸ Infer build/test cmds + deps ▸ Draft §0 index + sections ▸ You ratify: AI drafts, you correct ▸ Seed 1 baseline CHANGELOG entry One-time bootstrap pass → ② copilot-instructions.md .github/ — Copilot auto-loads it + Read PROJECT.md §0 first + MANDATE end-of-task ritual:   · write session-docs/SESSION_*   · prepend CHANGELOG.md   · refresh stale PROJECT.md § Keep it short — Copilot truncates ~15 lines; phrase as a Rule → ③ RUN THE RITUAL ▸ Create session-docs/ + template ▸ Every PR → one session log ▸ Prepend CHANGELOG (newest 1st) ▸ Refresh stale PROJECT.md § ▸ PR template / CI check enforces ▸ Durable calls → ADRs Steady state, every session AI prompt → generates PROJECT.md "Analyze this repo and write PROJECT.md.  Begin with §0 Quick index: section list  + token load-order. Then sections for  goals/non-goals, architecture, data  model, build & test cmds, §invariants.  Rank core modules by git-log churn.  Infer from code — cite file paths,  never invent. I will ratify & correct." .github/copilot-instructions.md ## Project memory (read first) - Read PROJECT.md §0 before planning;   open only the §(s) you touch. ## Session-end ritual — MANDATORY 1. Write session-docs/SESSION_<date>_<slug>.md    (Goals→Investigation→Plan→Verify→Tradeoffs) 2. Prepend newest-first CHANGELOG.md entry 3. Refresh stale PROJECT.md §sections
brownfield AI bootstrap mandate, not hint

Generating PROJECT.md is an AI job, not a typing job. Point an agent at the repo with the bootstrap prompt shown below-left: it crawls the source tree, mines git log for churn hotspots (the files that change most are your core modules), infers build/test commands and external deps, and drafts the §0 Quick index plus sections. You ratify — the AI proposes, you correct. Then seed CHANGELOG.md with one baseline entry and create an empty session-docs/ with a template.

The behavior change lives in copilot-instructions.md — Copilot's auto-loaded equivalent of CLAUDE.md (in .github/). Add a bootstrap rule ("read PROJECT.md §0 before planning") and the three-step session-end ritual, pointing session logs at session-docs/.

Phrase it as a hard mandate, not a suggestion. Agents reliably follow numbered Rules, not prose hints — a "please also update the docs" aside gets dropped under task pressure. Keep the file short; Copilot truncates long instruction files.

Key Insight

Brownfield adoption = a one-time AI bootstrap pass + a ~15-line edit to copilot-instructions.md. The hard part isn't writing the docs — it's the mandate that makes the agent maintain them.

← → navigate · 1–9 jump · Home/End