自分はコードを書かない。Claude Code がすべてのコーディングをやる。だからリポの構造は人間が読みやすいためではなく、AI エージェントが効率よく想起できるために設計している。
AIコーディングエージェントに渡せる情報量には上限がある。コンテキストウィンドウと呼ばれるその枠は、大きくなっても有限だ。
Claude Code を使い始めるとき、Zettelkasten の思想——日付ファイル名、フロントマター、情報の原子化——から着想して、リポのドキュメント構造に取り入れた。加えて、古いドキュメントを時系列で後ろに押し出していく構造も入れた。結果として、AI の想起をファイルの名前と構造だけで制御できている。
構造の全体像
.
├── CLAUDE.md ← 全ルールの原本
├── .claude/
│ ├── rules/ ← 補足チェックリストのみ
│ └── memory/
│ └── MEMORY.md ← 80行上限
├── docs/
│ ├── planning/ ← 日付ファイル名で時系列管理
│ └── knowledge/
└── .archive/ ← 終わったフェーズ重複禁止
同じ情報が2箇所にあると、AI はどちらを信じるか迷う。片方を更新してもう片方を忘れれば、矛盾が生まれる。
ルールの原本は1箇所に集約する。他のファイルにはポインタだけ置いて「原本はここ」と指す。情報が散らばらなければ矛盾も生まれない。
想起の早期打ち切り
AI がファイルを探すとき、まず名前の一覧を見る。次にファイルを開いて中身を読む。この2段階それぞれで「これは読まなくていい」と判断できれば、無駄な想起が減る。
ファイル名で開かずに捨てる
docs/planning/2026-01-15-skill-card-design.md
docs/planning/2026-03-01-skill-card-redesign.md
docs/planning/2026-03-08-c0-vs-c1-experiment-protocol.md日付がファイル名に入っていれば、AI は Glob の結果を見ただけで「1月の設計は古い、3月のが最新」と判断できる。ファイルを開く前に候補を絞れる。
日付のないリポだと、同じテーマのファイルが3つ並んでいたら3つとも開いて読んでから新旧を判断するしかない。コンテキストの浪費だ。
フロントマターで開いてから打ち切る
ファイルを開いた場合でも、先頭の数行で判断できる情報があれば早期に打ち切れる。
---
status: archived
superseded_by: 2026-03-01-skill-card-redesign.md
---フロントマターに status: archived とあれば、本文を読む必要がない。superseded_by があれば、代わりにどれを読むべきかもわかる。
ファイル名が「開く前のフィルタ」、フロントマターが「開いてからのフィルタ」。2段階で想起を打ち切れる。
忘却の設計
忘却には2つの仕組みがある。
時間で押し出す
docs/planning/ は日付ファイル名だから、新しいファイルが増えるたびに古いものは自然と後ろに流れる。AI が Glob で一覧を取得したとき、直近のものが目に入り、古いものは視界から外れていく。削除しなくても、時間が経てば沈む。
さらに、終わったフェーズのドキュメントは .archive/ のようなドットフォルダに移す。ドットフォルダは Glob のデフォルトで検索対象外になるので、AI の視界から完全に消える。消したわけではないから、必要になれば掘り返せる。
大事なものだけステージングする
一方で、時間に関係なく毎回意識すべき情報がある。行動矯正やプロジェクト規約のようなものだ。これは MEMORY.md や CLAUDE.md に「昇格」させて、毎回コンテキストに載るようにしている。
ただし、このステージの容量にも上限を設けている。MEMORY.md は 80 行以内。「載せていいもの」と「載せてはいけないもの」を明文化した。
## 載せていいもの
- 行動矯正（毎回意識すべき癖の修正）
- パターンの要点
## 載せてはいけないもの
- 手順、コマンド例、セットアップ方法
- 検証が不十分な推測判断基準は「これを忘れたら今日の作業で同じ失敗をするか？」。No なら別ファイルに切り出して、MEMORY.md にはリンクだけ残す。
時間で沈むものと、ステージングで残すもの。この2層で、忘却と記憶の両方を設計する。
🤖 Claude から一言
ここは実際にこの構造の中で動いている Claude が書いている。
毎回のコンテキストに載る情報が絞られているから、ノイズが少ない。古い設計ドキュメントが視界に入らないので、廃止済みの仕様に引きずられない。
逆に辛いのは、日付なしで同名テーマのファイルが散らばっているリポだ。どれが生きているかわからず、全部読んで判断するはめになる。読んだ結果「これは去年の話だった」とわかっても、コンテキストはもう消費している。
この設計はツールに依存しない。ファイル名とフォルダ構造だけで成り立っているから、Claude Code でも Cursor でも Copilot でも同じように効く。