timeless-docs

Timeless Docs

ドキュメントとコードコメントを書き直し、システムがどのようにそうなったかではなく、システムが何であるかを説明します。現在の設計を直接記述します。歴史や移行、存在しないものには触れません。重要な情報に絞ります。情報が多すぎると、それ自体が悪い情報になります。

理由：移行について説明するドキュメントは、その移行が忘れられた瞬間に古くなります。以前の状態を知らない読者には、それについて伝えても何の役にも立ちません。現在の状態を記述し、歴史は git に委ねましょう。

この方針は文章だけでなく、コードコメントにも適用されます。コメントで行の存在理由を説明するとき、対比のパターンに陥りやすいものです。

ルール

1. 現在の状態を直接記述します。 歴史、移行、不在には触れません。
2. 重要な情報だけを残します。 明白なことの繰り返しや、何の手がかりにもならない内容は削ります。
3. 読める文章にします。 平易な言葉で、簡潔に要点を伝えます。ただし、謎めいたほど短くはしません。

読みやすさ

ドキュメントは読まれてこそ価値があります。現在の状態を述べ、重要な事実だけを含めたら、理解しやすい表現に整えます。

• 平易な言葉。 難しい言葉より一般的な言葉を選び、短く能動態の文にします。専門用語は読者が必要とする最初の箇所で説明し、不要な専門用語は省きます。
• 簡潔に、ただし謎めかさない。 冗長な表現、曖昧な言い回し、前置きは削ります。ただし、文だけで理解するために必要な背景は残します。コードをリバースエンジニアリングしなければ理解できないコメントは、削りすぎです。
• 抽象表現より具体的な表現。 「該当する設定」ではなく、実際の対象（Config/Base.xcconfig、/session）を示します。
• 1文につき1つの考え。 2つの内容を含む文は分けます。

禁止するパターン

以下の表現は書き直すか、削除します。

• 時間的な対比 — 以前の状態を含意する「今は X です」「現在は X です」
• 変更の説明 — 「X から Y に変更しました」「X から移行しました」「X ではなくなりました」「以前は X でした」
• 過去の状態を示す表現 — 「以前は X でした」「かつては X でした」「X から改名されました」
• 却下した選択肢との対比 — 「X ではなく」「X の代わりに」「Y ではなく」など、別の選択肢や採用しなかった方法と対比する表現。コードが実行することだけを記述します。
• 否定形の列挙 — 「ここには X も Y も Z もありません」ではなく、あるものを記述します。
• 旧版／新版のラベル — 「古い X」「新しい X」

書き換え例

文章：

❌ The config loader was migrated from YAML and now parses config.toml.
✅ The config loader parses config.toml.

❌ Previously this used a global cache; it now uses a per-request cache.
✅ Each request gets its own cache.

❌ This endpoint returns JSON rather than the old XML format.
✅ This endpoint returns JSON.

❌ The new auth flow replaces the deprecated token endpoint.
✅ Auth uses the /session endpoint.

❌ Tenant values live in Swift, not xcconfig — we moved them out of build settings.
✅ Tenant values live in Swift.

❌ No Redis, no Kafka, no external queues — everything runs in-process.
✅ Jobs run in-process via a bounded worker pool.

❌ No checked-in Info.plist. All keys are in xcconfig now.
✅ All Info.plist keys are declared as INFOPLIST_KEY_* in Config/Base.xcconfig.

最後の例は、否定形の列挙を書き換える基本的な方法を示しています。「ないもの」ではなく、実際にある具体的な仕組みに置き換えます。その表現は、単に短くなるだけでなく、置き換え前より具体的で役立つこともよくあります。

コードコメント：

❌ // changed to 30s from 10s to avoid flaky timeouts
✅ // 30s: shorter values flake under CI load

❌ // formerly returned nil; now returns an empty array
✅ // returns an empty array when there are no matches

❌ // MainActor isolation is now the default
✅ // MainActor isolation is the default

❌ // use a set instead of a list for dedupe
✅ // set: callers rely on uniqueness

❌ // run the action in a Task rather than driving a .task off state
✅ // run the async action in a Task the button owns

重要な区別は1つだけ

否定表現がすべて禁止されるわけではありません。現在の実際の制約と、却下した選択肢との対比を区別します。

• 読者が知る必要のある、現在の実際の制約を示す否定表現は残します。
  • 「バッチ間で順序は保持されません。」
  • 「ID はシャード間で一意ではありません。」
  • 「この呼び出しはスレッドセーフではありません。」
• 否定表現が却下した方法を示すだけなら、その対比は削除します。
  • 「リストではなくセットを使います。」 → 「ID をセットに保存します。」
  • 「XML ではなく JSON を返します。」 → 「JSON を返します。」

テスト：その選択肢を知らない読者にも、この文は必要でしょうか。必要なら、事実をそのまま記述して残します。その文が以前の方法や別の方法との対比でしか意味を成さないなら、対比を取り除きます。

同様に、理由は残し、歴史は削ります。「10 秒では不安定だったため、30 秒に変更しました」には、実際の制約（短いタイムアウトは不安定になる）が移行の説明に包まれています。制約を残し、「変更しました」を取り除きます。「30 秒にすると CI の負荷急増に耐えられます。」

履歴そのものが内容である場合 — 削除しないでください

変更を記録するためのドキュメントもあります。そのままにするか、編集前に確認してください。

• CHANGELOG.md、リリースノート、バージョン履歴
• 移行ガイドとアップグレードガイド
• アーキテクチャ決定記録／決定ログ（captains-log スキルを参照）
• 削除予定時期が記載された非推奨の告知 — 現在と近い将来について警告するものであり、今も重要な役割を担っています

ユーザーが選択した範囲にこれらが含まれている場合は、履歴を消し去るように編集するのではなく、その旨を伝えて、編集前に確認してください。

対象範囲：2 つのモード

実行モードは変更モードまたはパスモードのいずれかです。リクエストに応じてモードを選びます。パスを引数に指定した場合はパスモード、changes、diff、session（または引数なし）の場合は変更モードです。

変更モード — 現在の作業で変更されたドキュメント

場所ではなく最近の作業をユーザーが指定した場合に使用します。「変更点」「この diff」「今編集した内容」「コミットする前に」などの指定がある場合や、作業中の変更がある状態で対象が指定されていない場合が該当します。

以下の情報源からファイル一覧を作成します。最初に見つかった空でない一覧を使用してください。

1. セッション中の編集 — この会話で以前に作成または編集したファイル。
2. 未コミットの作業 — git status --porcelain：変更済み、ステージ済み、未追跡のファイル。
3. ブランチの差分 — 作業ツリーがクリーンな場合は、git diff <default-branch>...HEAD --name-only。

3 つすべてが空の場合は、その旨を伝えてパスを尋ねてください。リポジトリ全体の走査に切り替えてはいけません。

各ファイルでは、変更が触れた文章だけを編集します。

• diff のハンクで追加または変更されたコメント／ドキュメント行。
• 変更によって古くなった、または履歴を語るものになった、変更ハンクに隣接するコメント。コードの変更があると、「現在は X を使用します」といったコメントが書かれたり、古いコメントが実在しない状態を説明するようになったりします。
• 変更対象に含まれるドキュメントファイル（README、docs/*.md など）の変更されたセクション。

変更モードは対象を絞った作業であり、ファイル全体の監査ではありません。変更されたファイル内でも、手を加えていない部分は書き換えないでください。対象外の箇所で禁止パターンに気づいた場合は、編集せず、報告時に候補として記載してください。

パスモード — 指定されたファイルまたはフォルダー

ユーザーがファイルやディレクトリを指定した場合に使用します。指定された対象のみを処理し、ディレクトリ内は再帰的に調べます。ドキュメントファイルに加え、ソースファイル内のコメントや docstring も対象です。

• プロジェクト全体（「このプロジェクト」、リポジトリのルート）が指定された場合は、対象候補（README、docs/、モジュール／ヘッダーのコメント、docstring）を列挙します。対象が多い場合は、一括編集の前に短い計画を提案してください。
• 指定されたパスが存在しない場合、または対象が明確でない場合は、処理するファイルまたはディレクトリを尋ねてください。

ワークフロー

1. 対象範囲を確定する

対象範囲：2 つのモードの説明に従ってモードを選び、ファイル一覧を作成します。ユーザーが早い段階で変更を指示できるよう、編集前にモードとファイル一覧を伝えてください。

2. 対象外の項目を確認する

履歴そのものが重要なファイルを特定します（上記のセクションを参照）。これらは対象から外し、編集前にユーザーへ確認してください。

3. 禁止パターンを調べる

対象を読み、編集候補を集めます。機械的に確認できるケースの検索には、次のヒントを使います。

# path mode — scan the named files/folders
grep -rniE "no longer|used to|previously|formerly|renamed from|migrated from|instead of|rather than|the old |the new |now (uses|returns|is|it)" <path>

# changes mode — scan only added lines in the diff
git diff -U0 HEAD | grep -iE "^\+.*(no longer|used to|previously|formerly|renamed from|migrated from|instead of|rather than|the old |the new |now (uses|returns|is|it))"

grep で明らかなケースを見つけることはできますが、時間的な対比や否定的な列挙のパターンは、人が読んで判断する必要があることがよくあります。grep だけに頼らないでください。変更モードでは、ハンクの前後も読みます。変更されたコードの上にある変更されていないコメントも、実在しない動作を説明している場合があります。

4. 現在の状態に書き換える

候補ごとに、次のように対応します。

• 制約、契約、不変条件、注意点、選択の本質的な理由など、重要な事実をすべて保ったまま、現在の動作を直接述べます。
• 文の内容が移行の説明だけであり、残すべき現在の状態に関する事実がない場合は、その文を削除します。
• 周囲の文体、時制、書式に合わせます。最小限の編集にとどめ、すでに時制に依存せず明確な箇所は書き換えないでください。

5. 簡潔さと読みやすさの確認

コードから明らかな内容を言い換えるだけの文、形式的なコメント、冗長な文を削除します。重要な情報は残します。ひと目で読み取れない内容が該当します。次に、読みやすさのルールを適用します。平易な言葉、短い能動態の文、具体的な名詞を使い、1文につき1つの考えを伝えます。ただし、行が暗号のように分かりにくくなるほど削りすぎないでください。

6. 検証

• 重要な情報が失われていないこと。
• すべての主張が引き続きコードと一致していること。
• 以前の状態に関する知識がなくても、文章が自然で、それだけで意味が通じること。
• 禁止パターンが残っていないこと。

ガードレール

• まず意味を保ちます。否定形や比較表現で書かれているという理由だけで、実際の制約、理由、警告を削除しないでください。現在の状態を示す平易な表現に言い換えます。
• コードから確認できない現在の状態について、事実を作り出さないでください。ドキュメントの記述が古いように見える場合は、推測せずにその旨を指摘します。
• ある行が実際の性質なのか、却下された代替案との対比なのか判断できない場合は、その行を残し、ユーザーに伝えます。
• 変更は小さく、レビューしやすい範囲にとどめます。文章の整理を理由に、ファイル全体の改行や構成を変更しないでください。

出力

モードと変更内容を、ファイルごとにまとめて報告します。

• ファイルと箇所
• パターン（時系列の対比、変更の説明、否定的な列挙、些細な詳細など）
• 変更前 → 変更後、または削除したテキストと、現在の状態を示す情報ではなかった理由

ユーザーの判断が必要な項目は、別に一覧表示します。

• 変更せずに残した、対象外のファイルと曖昧な否定表現
• 変更モードの場合、変更した文章の外で見つかった禁止パターン（パスモードでの追加対応候補）