資料の書き方をそろえる — AIが1ファイルで迷わない冒頭と目次を決める

資料が増えると、AIも自分も「このファイルは何を書く場所だったか」を見失う。開くたびに全文を読み直すことになり、書き足す場所も毎回ずれる。この章では、冒頭の書き方を固定して、開いた瞬間に役割が分かる状態を作る。決めるのは4つで、どれも1行の決めごとになる。

目次

---

1. 何が起きるのか

最初の数ファイルは、どこに何を書いたか覚えている。崩れ始めるのは20ファイルを超えたあたりになる。

崩れる場所は決まっている。

冒頭が案内板になる。 ファイルを開くと「◯◯は別ファイルが正本」「△△については向こうを参照」と前置きが並び、本題まで辿り着かない。しかも同じ案内が複数のファイルに書かれているため、ファイルを1つ増やすたびに直す場所が増えていく。

AIが書き足す場所を間違える。 「このルールを資料に追記して」と頼むと、似た話が書いてあるファイルに足される。役割が明示されていなければ、内容の近さで判断するしかない。結果、同じことが2箇所に書かれた状態になる。

変更の経緯が本文に溜まる。 「以前はAだったが、8月にBへ変えた」という記述が積もると、読む側は「今どっちなのか」を判別しながら読むことになる。AIも同じで、旧仕様を現行と誤読する。

いずれも、1ファイルの書き方が決まっていないことから来ている。

2. どう決めたか

決めたのは4つになる。

決めごと1:冒頭の順番を固定する

各ファイルの冒頭を、次の順にする。

1. タイトル(見出し1)
2. 戻りリンク(索引ファイルがあるフォルダーでは、そこへ戻る単方向リンク)
3. 概要(その資料自身が何を扱うか。1〜数行)
4. 目次(表形式)

いきなり本文から始めない。読み手が「この資料に何が書いてあるか」を数秒で把握できることを優先する。

そして概要には、その資料自身が何を担当するかだけを書く。以下は書かない。

ただし、本文中の参照は残してよい。禁止するのは「冒頭で他ファイルの責務を先に説明すること」であって、リンクそのものではない。読者がその場で必要とする地点に置かれた導線は残す。

決めごと2:目次を3列の表にする

目次は「章」「タイトル」「内容」の3列を持つ表にする。

## 目次

| 章 | タイトル | 内容 |
|---|---|---|
| 1 | ○○ | ×× |
| 2 | ○○ | ×× |

すべての見出しを網羅しなくてよい。大枠の章が分かれば足りる。

「内容」列を見出しの言い換えで終わらせない。 「1. 冒頭構成 → 冒頭の構成について」では何も足していない。「概要→目次の順で書く。概要には自分の責務だけを書く」まで書いて、初めて目次から中身が引ける。

決めごと3:ファイル名に連番を付けない

01_、00- のような連番プレフィックスを付けない。順序はファイル名ではなく、索引ファイルの並びで表現する。

あわせて、各ファイルの末尾に「← 前 / 次 →」のような順序ナビも置かない。各ファイルからは「索引に戻る」への単方向リンクだけを置く。

例外は2つある。ユーザーが明示的に連番を指示した場合と、番号そのものが意味を持っている場合になる。適用順序を表す番号(セキュリティルールを1番に置く、など)は、順序を表す飾りではなく識別子として機能しているため対象外にする。

決めごと4:本文には最新版だけを書く

変更の経緯・いつ変えたか・旧仕様がどうだったかを本文に残さない。

ただし根拠は残す。この切り分けは5章で扱う。

3. なぜ概要に他ファイルの説明を書かないのか

冒頭に案内を並べたくなる気持ちには理由がある。読み手が間違ったファイルを開いてしまうのを防ぎたいからである。実際、書いた直後はうまく機能する。

問題は、ファイルが増えたときの直す場所になる。

AとBとCの3ファイルがあり、それぞれの冒頭に他2つとの住み分けが書いてあるとする。ここにDを足すと、A・B・Cの冒頭を全部直すことになる。しかも直し忘れても、書いてあることは間違っていないため気付けない。「Dについて触れていない」ことは、読んでも分からない。

ファイル数が増えるほど、直す場所は掛け算で増える。

そこで、ファイル同士の関係は索引ファイル側に集約する。Dを足したときに直すのは索引1つで済み、しかも索引を見れば全体が揃っているかが一目で分かる。

各ファイルは自分の中身だけに集中させる。 これは「置き場所をそろえる — フォルダーごとの構成ファイルで全体像を1箇所に集める」で扱う索引の作り方と対になっている。片方だけを採り入れると、追い出した情報の行き場がなくなる。

4. なぜ連番を付けないのか

連番は、並び順が目に見えるという分かりやすい利点がある。それでも付けないのは、変更のコストが連鎖するためになる。

03_ と 04_ の間に1ファイル足すとする。やることは3つある。

1. 新しいファイルを 04_ にする
2. 既存の 04_ 以降を全部リネームする
3. リネームしたファイルを参照しているすべてのリンクを張り替える

3つ目が問題になる。参照は資料のあちこちに散らばっているため、どこから参照されているかは検索しないと分からない。1つ見落とすとリンク切れになり、リンク切れは踏むまで気付けない。

ファイルを1つ足すだけの作業が、リポジトリ全体の張り替えになる。 これが起きると分かっていると、ファイルを足すこと自体をためらうようになる。

順序を目次側で持てば、ファイルを足すときに直すのは目次の1行だけになる。並べ替えも、目次の行を入れ替えるだけで済む。ファイル名は一度決めたら変わらないため、リンクも壊れない。

末尾の前後ナビを置かないのも同じ理由になる。 順序が変われば、前後2ファイルのリンクを直すことになる。ただしこれは、順序そのものが学習経路になっている連載記事では例外を認めている。読者が上から順に読む前提があるなら、毎回目次へ戻らせる方が損になる。

5. なぜ変更の経緯を本文に残さないのか

資料を開くのは「今どうなっているか」を調べるためになる。経緯が混ざると、読み手はどれが現行でどれが過去の話かを判別しながら読むことになり、資料が長くなるほど読めなくなる。

変更履歴はGitが持っている。 バージョン管理の仕組みを使っているなら、いつ何を変えたかは全部記録されている。本文に二重に持つ必要がない。

ただし、何もかも消すと別の問題が起きる。なぜその設計なのかを消すと、同じ検討を後から繰り返すことになる。 半年後の自分が「この分け方、非効率では」と思って戻し、また同じ理由で分け直す。

そこで、経緯と根拠を分ける。

判断の基準は1つになる。

過去の状態に言及せずに書けるなら、それは根拠であって経緯になる。

「AからBへ変えた理由」は経緯で、「Bである理由」は根拠になる。同じことを説明していても、前者はAを知らない読者には通じず、後者は誰にでも通じる。

経緯そのものを残したい場合は、専用の記録ファイルを作る。本文には混ぜない。そこは「経緯を読むために開くファイル」なので、日付と旧仕様を書いてよい。この使い分けは「繰り返す作業を型にする — skillの設計資料を4ファイルで持つ」で扱う。

6. 自分で作る手順

手順1〜4:ルールを書く

rule/文書作成ルール.md のようなファイルを作り、2章の4つの決めごとをそのまま書く。①で作ったルールと同じフォルダーに置く。

「書かない内容」は表にする。 文章で「他ファイルの説明は書かないこと」と書くより、具体例つきの表の方が判断がぶれない。書いてよいか迷ったとき、表の行と照らせば済む。

模範例を1つ指定する。 自分の資料の中で、いちばんうまく書けているファイルを選び、「新規作成する資料はこの形式に合わせる」と書く。抽象的なルールだけだと解釈の幅が出るが、実物があれば揃う。

手順5:AIが必ず読む場所から参照する

CLAUDE.md のような、会話の最初に読まれるファイルに1行足す。

- Markdown文書を新規作成・大幅編集する → rule/文書作成ルール.md
  (冒頭構成・目次の粒度・命名。**概要には自分の責務だけを書く**)

括弧の中に、いちばん破られやすいルールを1つ書いておく。 全部は書けないので、経験上いちばん戻りやすいものを選ぶ。

既存の資料をどうするか

一度に全部直さない。 20ファイルあれば、直すだけで数時間かかる。しかも直している間に何も進まない。

触ったファイルから直す。資料を編集する機会が来たとき、ついでに冒頭を整える。半年ほどで、よく使うファイルから順に揃っていく。使わないファイルは古い形のまま残るが、使わないのだから困らない。

連番についても同じで、既に連番が付いているフォルダーを慌てて直さない。リネームする機会が来たときに外す。新しく作るものにだけ、最初から付けないようにする。

効いているかの確かめ方

新しい資料をAIに書かせてみる。指示は「◯◯についての資料を作って」だけにする。

冒頭がタイトル→概要→目次の順になっていて、概要に他ファイルの話が入っていなければ効いている。案内板から始まっていたら、手順5の参照が届いていない。

次のページ

ここまでで、1ファイルの中身の書き方が決まった。開いた瞬間に何のファイルか分かり、書き足す場所も迷わなくなる。

ただし、この章では意図的に追い出した情報がある。「他のファイルとの関係」である。3章で触れたとおり、これは各ファイルの冒頭ではなく、索引側が持つ。③では、その索引をフォルダーごとに1つ置く形を決める。どこに何があるかを1ファイルで引ける状態を作る。

← ① 意図しない課金を止める ｜ 次:③ 置き場所をそろえる →