AIToday
Large Language ModelsAI Coding AssistantsZenn AI/MLPublished: Nov 22, 2026, 16:00 JST

Claude Code handover notes that grew to 1,630 lines caused false reports: write only in-progress items

Send on LINE
Claude Code handover notes that grew to 1,630 lines caused false reports: write only in-progress items

3 Key Points

  1. What happened

    A developer's task.md grew to 1,630 lines, about 45% records of finished work, and Claude reported 63 unfinished articles when all were done, because one item's status lived in four places.

  2. Why it matters

    Claude is only as reliable as the note it reads, so a handover file with stale flags can make a competent assistant report finished work as pending, and the fix is one status source plus deleting finished rows.

Not sure about something? Ask the AI

Questions and answers are published on this page.

Summaries like this, every morning.

Context & Analysis

The failure the author describes is not a model limitation but a bookkeeping one. Because a single item's status lived in a heading emoji, a table of contents, the body text, and an outside ledger, updating one copy left the others stale. Claude read an older flag and reported finished work as remaining — three times in one conversation. The correction was structural: split the index (MEMORY.md), the in-progress handover (HANDOVER.md), and stable knowledge into separate files, so changing state never means editing knowledge and vice versa.

The author's later refinements follow the same logic. Finished rows are deleted rather than archived in place, decisions get their own ledger with a column for whether they may be proposed again, and status moves to OPEN.md once a project reaches dozens of items. The table of contents was dropped because it duplicated status. The rule that a number should be looked up at its source rather than copied treats every figure in a note as something that starts aging the moment it is written.

Reading is enforced rather than assumed. After a conversation opened in a different folder began work without reading the project notes and broke a rule, the author paired a SessionStart hook that injects a reading list with a PreToolUse check that blocks the first edit or push if the log shows no sign of reading it. The author notes the same split of index, handover, and individual knowledge files is packaged, with personal values removed, in a paid template called AI organization kit, which he says is not an official Anthropic product.

FAQ
What exactly went wrong with the 1,630-line handover note?
It contained about 45% records of finished work, and each item's status was written in four places. When one place was updated, Claude read an older flag and reported finished work as remaining.
How does the author handle numbers like counts and versions in handover notes?
He does not copy them. Instead of writing that 23 sales leads remain, the note says to count the status column in sales/list.csv, so the next conversation reads the current source rather than a stale figure.
What are OPEN.md and DECISIONS.md for?
OPEN.md is the single source of truth for the status of open items, one row per item. DECISIONS.md records what a human decided, one row per decision, including whether the proposal may be raised again.
Send on LINE

AI news that matters for your work, delivered every morning.

Pick your industry and the AI tools you use, and get news related to your work every day.

Free · 30 seconds with Google · unsubscribe anytimeWhat is AIToday? →

Ask AI

Ask AI anything about this article. The AI reads this article, earlier AIToday articles, and Wikipedia, and cites its sources. Q&As are published on this page for other readers too.

Questions and answers are published on this page.

Related Articles

Next articleJerry Newman: AI's Big Winners May Not Be AI Companies