No More Documentation Debt: A Claude Code Plugin That Records Your Dev Process

No More Documentation Debt: When Your Development Process Documents Itself

1. Two Old Problems

Every developer owes two debts.

The first is documentation debt. Writing docs is a burden: features keep changing and the docs go stale. Not writing docs is a disaster: three months later you stare at your own code and spend half a day remembering "why on earth did I build it this way?" You are forever torn between "write it" and "skip it".

The second is handover debt. When a project changes hands, the best onboarding you can offer is "just ask me if you have questions." Once the original developer is gone, the code becomes a black box. The newcomer can read every line of syntax but none of the decisions behind it.

AI-assisted programming makes this worse in a subtle way: your conversations with the AI carry most of the development process — how requirements were clarified, how alternatives were weighed and rejected, how pitfalls were stumbled into and climbed out of. Those conversations are more complete and more honest than any document you could write. And yet, the moment the session closes, the process evaporates.

What if this "most complete documentation" could be kept automatically?

2. ai-tracedoc: Your Development Process, Written into a Ledger

ai-tracedoc is an MIT-licensed Claude Code plugin. It does exactly one thing:

Automatically records your questions and the AI's final answers, round by round, into a TraceDoc ledger in the project root.

How it works, in three lines: after every AI response, the plugin extracts that round's Q&A from the local session transcript; it does a final flush when the session ends; everything is appended incrementally to a single Markdown file. You do absolutely nothing.

Install:

claude plugin marketplace add didongke/ai-tracedoc
claude plugin install ai-tracedoc@ai-tracedoc

Enable (once per project):

touch .tracedoc-on

From then on, the ledger grows on its own:

## 2026-09-14 · Cache Design

**Question:** 2026-09-14 10:23 · Why LRU instead of LFU here?
**Answer:** LRU is simpler to implement, and our access pattern is dominated by recent hot data… (the AI's answer, verbatim)

**Question:** 2026-09-14 10:31 · What should the memory cap be?
**Answer:** At roughly 200 bytes per record… (the AI's answer, verbatim)

3. Three Things It Gives You

① Documentation at zero cost. No writing, no extra steps. The ledger is a by-product of development — your questions, the AI's answers, the trade-offs you considered, all settle into text automatically. Documentation stops being a debt because it grows by itself.

② The AI gains project memory. Hand the ledger and the code to an AI, and it will understand not just what the architecture is, but why decisions were made and what pitfalls were hit. Maintenance changes fundamentally: the AI no longer works blind — it arrives with the project's full backstory.

③ The project becomes handover-ready. Code + ledger = complete development context. Give both to anyone, and they can continue developing and maintaining the project with AI. Handover no longer depends on "asking the person who was there" — because the person's thinking is in the ledger.

4. An Example: From Development to Handover

Here is a full timeline.

Day 1. Li is building a payment module with Claude Code. He works as usual — asking, rejecting, deciding — without writing anything extra:

## 2026-08-03 · Payment Module Development

**Question:** 2026-08-03 09:41 · Which third-party payment provider — WeChat or Alipay direct?
**Answer:** Both charge the same fee rate, but WeChat's refund API docs are more complete… (verbatim)

**Question:** 2026-08-03 09:52 · What if we need both channels later?
**Answer:** I'd suggest abstracting a PayChannel interface so channel implementations are pluggable… (verbatim)

**Question:** 2026-08-03 10:15 · How do we make the payment callback idempotent?
**Answer:** Use order ID plus a state machine. The classic pitfall here is duplicate callbacks causing double booking… (verbatim)

Day 60. A new requirement arrives: add another payment channel. Li (or whoever took over) hands the ledger and the code to the AI:

"Read this project's ledger and code. We're adding an Apple Pay channel — what should I watch out for?"

The AI's answer is no longer generic advice — it comes with the project's history attached: "According to the decisions in the ledger, the channel layer was built as a pluggable interface, so a new channel only needs to implement three methods. Watch out for callback idempotency — you hit the duplicate-callback problem on August 3rd, and the ledger records the handling as…"

Architecture, decisions, and pitfalls — all present, no need to ask the original developer.

Without the ledger, the same scenario plays out differently: the AI can only guess the architecture's intent from the code, or hand you a generic checklist that fits any project. Once the original developer is gone, the decisions and the pitfalls are gone forever.

A real example: ai-tracedoc was developed exactly this way. During development we hit a bug — the ledger didn't update when the user exited with /quit. It was the Q&A sequence in the ledger that let us localize it quickly (exit method → hook trigger conditions → root cause), and the fix is recorded there too. Today, anyone can ask an AI in that repository "why does recording use a Stop-hook fallback?" and get the full story as it happened.

5. Pairs Perfectly with Git: A Complete History

On its own, the ledger records the process. Combined with git, its value doubles.

• git records the "what": every commit tells you what changed and when
• the ledger records the "why": the discussion, decisions, and pitfalls behind every change

Both live in the same repository, and their timelines align naturally: find a commit, flip to the ledger to see the discussion behind it; find a decision in the ledger, and git log shows the code that made it real. Together they give a project its first complete, traceable history — code and decisions, both accounted for.

6. Why This Works: Record Faithfully, Never Infer

Many "auto-documentation" approaches ask an AI to write a summary afterwards. We deliberately didn't, for one simple principle:

The decision is not in the AI's summary. It's in your next question.

You ask "why LRU", the AI answers, you say "let's go with it" — the decision chain lives naturally in the Q&A sequence and needs no distillation. Distillation inevitably distorts, and when an AI analyzes a project, what it needs is the raw process, not a second-hand summary.

This principle comes with extra benefits:

• Zero token cost: recording calls no model at all
• Zero hallucination: the ledger contains only actual words, no "reasonable reconstructions"
• Verbatim in any language: Chinese stays Chinese, English stays English — content is never translated

7. Engineering Details (the part developers will check)

Reliability is the foundation of this plugin:

• Round-by-round capture: every Q&A lands in the ledger as soon as the AI finishes answering — the exit method doesn't matter. Ctrl+C, closing the terminal, a killed process: nothing already recorded is lost
• Incremental dedup: claude -c session continuations never duplicate entries
• Automatic volumes: past 200 KB the ledger rolls into new volumes with cross-links
• Concurrency-safe: a project-level file lock guards the whole read-modify-write path
• 65 unit tests, GitHub Actions CI, bilingual documentation

One Easter egg: this plugin recorded its own entire development process — from the requirements discussion, through hook-mechanism experiments, to the root-cause analysis of three bugs. Its GitHub repository is a living sample of how it works.

8. Honest Boundaries

• Tested on Linux only (Claude Code 2.1.260); macOS is expected to work but untested; Windows is not supported
• It relies on Claude Code's internal transcript format — after a major upgrade, if recording stops, verify with --self-test
• The ledger contains verbatim conversation content, which may include code snippets or sensitive information. It is not committed to git by default — review before sharing

9. Closing

Code is a project's present; the ledger is its history. Only together is a project complete.

If your team uses Claude Code, give it a try — it never interrupts you. It just quietly keeps every thought you had.

GitHub: didongke/ai-tracedoc · MIT · Stars, issues, and feedback welcome.