新しいディレクトリ構成を決めるとき、見た目をすっきりさせることだけを優先すると、必要なテストや判断の記録まで失いかねません。テストの置き場所、仕様とADRの役割、計画の凍結、草稿の削除には、それぞれ守るべき境界があります。

以下では、開発資産を整理するための6つの原則をまとめます。本文に出てくる新しいパスはすべて候補であり、作成・移行済みという意味ではありません。

1. テストは集中管理を基本に。ただし言語の事情を優先する

「テストは一か所にまとめる」を基本方針にするのは有効です。ただし、あらゆるテストをソースコードのディレクトリから移す、と決めつける必要はありません。

• Python：まず tests/への集約を検討します。移行時には、インポート、テストの検出、フィクスチャ、CIの設定も確認してください。このリポジトリのCI設定は、すでに集中管理されたテストパスを使っています。
• Go：非公開識別子にアクセスする白箱テストは、テスト対象と同じパッケージに置く場合があります。ブラックボックステスト、複数コンポーネントをまたぐテスト、エンドツーエンドテストは、集中配置を優先できます。Goではパッケージごとにテスト用ファイルを含めてビルドし、同じパッケージでのテストと、_test接尾辞を付けた外部テストパッケージの両方をサポートしています。1416

ここでは、内部パッケージをインポートできる範囲の制約と、非公開識別子にアクセスできるかどうかを混同しないことが大切です。internalパッケージのインポート制限は、そのディレクトリより上のパスを共有しているかに関わるルールです。「同じディレクトリにないとインポートできない」という意味ではありません。1016

したがって、「Goのテストをすべて業務コードのディレクトリから移し、白箱テストの範囲も維持し、カプセル化も変えない」ことを一律の合格条件にするのは適切ではありません。ディレクトリを整えるためだけに内部状態を公開したり、実装を重複させたりしないようにしましょう。

避けたいのは、価値の薄いチケットの細分化や、同じ確認の繰り返しです。継続的な回帰テストはバージョン管理し、一度きりの調査用プローブは一時領域に分けます。

2. 全体ルール、仕様、ADRは役割が異なる

specs/を「すべてのADRから共通項を抜き出したもの」と定義するのは避けましょう。全体ルール、プロジェクトの仕様、意思決定の記録は、次のように分けて考えると整理しやすくなります。

層	答える問い	内容の根拠
全体の方法論	どう分析し、検証し、成果を届けるか	方法論の管理者が定める
プロジェクトの入口 AGENTS.md	このプロジェクトではどう作業するか	確認済みの制約と作業上の入口
プロジェクト仕様 specs/	現在、どのような動作や契約を満たすべきか	ユーザー要件、受け入れ済みの判断、承認された改訂
意思決定記録 docs/adr/	なぜこの案を選んだのか	重要な設計上の判断、トレードオフ、代替案

Clineの公式ドキュメントは、複数の会話にまたがって使うルールの仕組みを説明しています。4 一方、Clineが特定の種類のファイルを仕様ディレクトリへ自動で書き込む、といった動作は、今回の根拠からは確認できません。そうした運用は、Clineの保証ではなくプロジェクト側の取り決めとして扱うべきです。

プロジェクト固有の内容は、すべて人が一から書く必要も、動的な問題が起きてから初めて作る必要もありません。たとえば、次の流れが考えられます。

1. 初期化時に、ユーザーの要望とリポジトリの根拠をもとに仕様案を作る。分からないことは分からないままにしておく。
2. タスクに着手するとき、関係する仕様と判断記録を読み、今回の受け入れ条件と検証方法を確認する。
3. 重要な新しい選択が生じた場合に、新しいADRを提案する。既存の判断が当てはまるなら参照し、計画ごとに同じADRを作らない。
4. 検証結果は、実装が条件を満たしたことを示す場合もあれば、仕様の問題を明らかにする場合もある。検証結果だけで要件が決まるわけではない。
5. 判断が承認され、仕様の更新も認められたら、現在有効な制約を該当する仕様に反映し、関連ADRを参照する。過去の経緯を丸ごと複製する必要はない。

要点は、仕様は現在の契約、ADRは判断の根拠、テストは実行可能な確認という区別です。互いに関連はしますが、代替関係ではありません。また、プロジェクト内の発見を、審査なしに全体ルールへ昇格させないことも重要です。

3. ADRの保存先を統一しても、受け入れの基準は変えない

新しい意思決定記録の標準的な保存先をdocs/adr/にする案は妥当です。これはプロジェクト内の命名・配置ルールであり、唯一の業界標準だと説明する必要はありません。

記録の運用では、次の点を保ちます。

• 提案中、受け入れ済み、却下、後の判断に置き換えられたものを記録できるようにする。受け入れ済みのADRだけを残す必要はない。
• 新しいタスクでは有効な既存の判断を再利用し、同じ内容のADRを繰り返し作らない。
• 判断が置き換えられたときは相互の関係を記録し、当時の理由を書き換えない。
• テストが通ったことだけで、ADRを受け入れる権限が生まれるわけではない。

移行時にはファイルを移すだけでなく、実際の参照先、ルーティング、権限制約も更新する必要があります。

4. 計画はフラットに管理してもよい。凍結は完了ではない

plans/に計画をフラットに置く方法は、過去の計画が少数なら十分実用的です。少ない履歴のために、必ずサブディレクトリを増やす必要はありません。候補となる命名例は次のとおりです。

用途	候補ファイル名	意味
現在の実行計画	pending_implementation_plan.md	標準の活動中エントリーポイントを1つにする
完了後の保存	plan-20261022-example-id.md	完了し、アーカイブが承認された計画
未完了のまま凍結	plan-20261022-example-id-frozen.md	未完了の項目を残し、通常の実行対象から外した計画

凍結のために新しいディレクトリを作る必要はなく、すぐに状態の種類を増やす必要もありません。現在のバリデーターは一時停止状態に対応しています。まずはそれを利用し、凍結ファイルに一時停止の理由、残作業、再開条件を記録できます。

次の3つは明確に区別してください。

• 完了・アーカイブ：必須の受け入れ条件をすべて満たし、アーカイブの承認を得た状態。
• 未完了のまま凍結：活動中の入口からは外すが、完了とはしない。未検証の提案を事実に格上げしない。
• 明確な放棄：実施しないことと、その影響を記録する。単なる一時停止として扱わない。正式な終了状態を追加するかどうかは、別途契約を改訂して決める。

通常は活動中のエントリーポイントだけを読み、同じディレクトリにある過去の計画を毎回すべて検索する必要はありません。過去の計画の再開や確認を求められた場合に、対象を絞って探します。凍結した計画を再開する際は、改めて承認を得て、元の計画への参照を残した新しい実行用インスタンスを作り、検証し直します。以前の「問題なし」という結果をそのまま引き継いではいけません。現在のライフサイクル規則とも整合する運用です。

ファイル名の変更は保存操作であり、受け入れ条件を満たした証明ではありません。上書きを防ぎ、未完了事項を残し、参照先も適切に処理しましょう。また、固定の入口ファイルを保つためだけに空の計画テンプレートを作る必要もありません。

5. テストとコードの対応は一対一ではなく、多対多で考える

「コード1つにつきテスト1つ」という対応を強制するのはおすすめできません。ひとつのテストが複数のコンポーネントを確認することもあれば、ひとつのコンポーネントに単体テスト、プロパティテスト、統合回帰テストが必要なこともあります。

まずは、次のような方法から始めるとよいでしょう。

• tests/の中を、モジュールや責務ごとに整理する。
• 関連する仕様に、重要な不変条件、テストの入口、有界な検証コマンドを記す。
• パス同士の対応が見つけにくい場合に限り、テスト対応表のような候補ファイルを追加する。

対応表に書くのは、モジュールまたは契約の識別子、ソースの範囲、テストの範囲、検証の入口といった必要最小限にします。ディレクトリ構造全体を複製したり、テストの合否を重ねて記録したりしないようにします。

保守上のチェックは、パスとコマンドが有効であることです。対応表があるだけで、十分なテストカバレッジやテストの成功が証明されるわけではありません。ファイルの散らかりを防ごうとして、すぐ古くなる台帳を増やさないことが大切です。

6. 草稿は整理できる。ただし、信頼性は置き場所だけでは決まらない

一度きりの草稿、一時スクリプト、探索レポートを.scratch/にまとめる方針は有効です。ただし、「この中の情報は一次情報として使えない」「いつでも全部削除できる」というルールにはしないでください。

• モデルが作成した調査要約は二次的な解釈であり、それだけで事実の根拠にはできません。
• 元のテスト出力や実際の診断記録は、一時ディレクトリにあっても一次証拠になり得ます。信頼性は、出所、環境、時点、記録の完全性によって判断します。
• 計画、判断、受け入れの根拠として参照されている唯一の証拠は、安易に削除できません。整理の前に必要な原本を残すか、その証拠に依存する結論を明確に取り消します。
• 重要な発見を整理して残すときは、根拠の場所、適用範囲、未確認事項も記録します。要約によって仮説が事実に変わってはいけません。

docs/にある古いレポートやアーキテクチャ図も、古いという理由だけで一律に不要とは限りません。「現在の保守対象」「明確に履歴資料としたもの」「未確認の資料」に分けて考えます。

• 現行文書には適用範囲を明記し、関連する契約が変わったときに見直す。
• 古い図や案には「履歴」「旧版」「置き換え済み」などの位置づけを示し、現在の基準としては扱わない。
• 長期的な価値も参照関係もない作業資料は、承認を得たうえで一時領域へ移すか削除する。

保存していることと、毎回読み込むことは別です。必要な履歴を残しつつ、毎回すべてを読まずに済むよう、対象を絞った読み込みと有効性の表示でコンテキストの混雑を防ぎます。証拠を消すことを優先する必要はありません。

まとめ：整理の前に、状態と役割を分ける

この構成は、次の4つの境界を守るなら、開発資産を整理する方向として妥当です。

1. テストは集中管理を基本にしつつ、言語ごとの例外を認める。
2. 仕様は現在の契約を示し、すべてのADRの要約にはしない。
3. 凍結は未完了の状態を保つ。完了やアーカイブとは区別する。
4. 一時資料を片づけても、唯一必要な証拠は失わない。

現在の標準計画パスと許可パス、および分析モードの編集範囲は、まだ旧構成に結び付いています。今後移行する場合は、ルール、テンプレート、参照、検証、ホスト環境への適応も合わせて更新する必要があります。ディレクトリ名を変えただけで移行が完了したと見なすことはできません。

なお、今回行ったのはセッション内での整理と分析のみです。資産の書き込み、移動、凍結、削除は行っていません。

新しいディレクトリ構成を決めるとき、見た目をすっきりさせることだけを優先すると、必要なテストや判断の記録まで失いかねません。テストの置き場所、仕様とADRの役割、計画の凍結、草稿の削除には、それぞれ守るべき境界があります。

以下では、開発資産を整理するための6つの原則をまとめます。本文に出てくる新しいパスはすべて候補であり、作成・移行済みという意味ではありません。

1. テストは集中管理を基本に。ただし言語の事情を優先する

「テストは一か所にまとめる」を基本方針にするのは有効です。ただし、あらゆるテストをソースコードのディレクトリから移す、と決めつける必要はありません。

• Python：まず tests/への集約を検討します。移行時には、インポート、テストの検出、フィクスチャ、CIの設定も確認してください。このリポジトリのCI設定は、すでに集中管理されたテストパスを使っています。
• Go：非公開識別子にアクセスする白箱テストは、テスト対象と同じパッケージに置く場合があります。ブラックボックステスト、複数コンポーネントをまたぐテスト、エンドツーエンドテストは、集中配置を優先できます。Goではパッケージごとにテスト用ファイルを含めてビルドし、同じパッケージでのテストと、_test接尾辞を付けた外部テストパッケージの両方をサポートしています。1416

ここでは、内部パッケージをインポートできる範囲の制約と、非公開識別子にアクセスできるかどうかを混同しないことが大切です。internalパッケージのインポート制限は、そのディレクトリより上のパスを共有しているかに関わるルールです。「同じディレクトリにないとインポートできない」という意味ではありません。1016

したがって、「Goのテストをすべて業務コードのディレクトリから移し、白箱テストの範囲も維持し、カプセル化も変えない」ことを一律の合格条件にするのは適切ではありません。ディレクトリを整えるためだけに内部状態を公開したり、実装を重複させたりしないようにしましょう。

避けたいのは、価値の薄いチケットの細分化や、同じ確認の繰り返しです。継続的な回帰テストはバージョン管理し、一度きりの調査用プローブは一時領域に分けます。

2. 全体ルール、仕様、ADRは役割が異なる

specs/を「すべてのADRから共通項を抜き出したもの」と定義するのは避けましょう。全体ルール、プロジェクトの仕様、意思決定の記録は、次のように分けて考えると整理しやすくなります。

層	答える問い	内容の根拠
全体の方法論	どう分析し、検証し、成果を届けるか	方法論の管理者が定める
プロジェクトの入口 AGENTS.md	このプロジェクトではどう作業するか	確認済みの制約と作業上の入口
プロジェクト仕様 specs/	現在、どのような動作や契約を満たすべきか	ユーザー要件、受け入れ済みの判断、承認された改訂
意思決定記録 docs/adr/	なぜこの案を選んだのか	重要な設計上の判断、トレードオフ、代替案

Clineの公式ドキュメントは、複数の会話にまたがって使うルールの仕組みを説明しています。4 一方、Clineが特定の種類のファイルを仕様ディレクトリへ自動で書き込む、といった動作は、今回の根拠からは確認できません。そうした運用は、Clineの保証ではなくプロジェクト側の取り決めとして扱うべきです。

プロジェクト固有の内容は、すべて人が一から書く必要も、動的な問題が起きてから初めて作る必要もありません。たとえば、次の流れが考えられます。

1. 初期化時に、ユーザーの要望とリポジトリの根拠をもとに仕様案を作る。分からないことは分からないままにしておく。
2. タスクに着手するとき、関係する仕様と判断記録を読み、今回の受け入れ条件と検証方法を確認する。
3. 重要な新しい選択が生じた場合に、新しいADRを提案する。既存の判断が当てはまるなら参照し、計画ごとに同じADRを作らない。
4. 検証結果は、実装が条件を満たしたことを示す場合もあれば、仕様の問題を明らかにする場合もある。検証結果だけで要件が決まるわけではない。
5. 判断が承認され、仕様の更新も認められたら、現在有効な制約を該当する仕様に反映し、関連ADRを参照する。過去の経緯を丸ごと複製する必要はない。

要点は、仕様は現在の契約、ADRは判断の根拠、テストは実行可能な確認という区別です。互いに関連はしますが、代替関係ではありません。また、プロジェクト内の発見を、審査なしに全体ルールへ昇格させないことも重要です。

3. ADRの保存先を統一しても、受け入れの基準は変えない

新しい意思決定記録の標準的な保存先をdocs/adr/にする案は妥当です。これはプロジェクト内の命名・配置ルールであり、唯一の業界標準だと説明する必要はありません。

記録の運用では、次の点を保ちます。

• 提案中、受け入れ済み、却下、後の判断に置き換えられたものを記録できるようにする。受け入れ済みのADRだけを残す必要はない。
• 新しいタスクでは有効な既存の判断を再利用し、同じ内容のADRを繰り返し作らない。
• 判断が置き換えられたときは相互の関係を記録し、当時の理由を書き換えない。
• テストが通ったことだけで、ADRを受け入れる権限が生まれるわけではない。

移行時にはファイルを移すだけでなく、実際の参照先、ルーティング、権限制約も更新する必要があります。

4. 計画はフラットに管理してもよい。凍結は完了ではない

plans/に計画をフラットに置く方法は、過去の計画が少数なら十分実用的です。少ない履歴のために、必ずサブディレクトリを増やす必要はありません。候補となる命名例は次のとおりです。

用途	候補ファイル名	意味
現在の実行計画	pending_implementation_plan.md	標準の活動中エントリーポイントを1つにする
完了後の保存	plan-20261022-example-id.md	完了し、アーカイブが承認された計画
未完了のまま凍結	plan-20261022-example-id-frozen.md	未完了の項目を残し、通常の実行対象から外した計画

凍結のために新しいディレクトリを作る必要はなく、すぐに状態の種類を増やす必要もありません。現在のバリデーターは一時停止状態に対応しています。まずはそれを利用し、凍結ファイルに一時停止の理由、残作業、再開条件を記録できます。

次の3つは明確に区別してください。

• 完了・アーカイブ：必須の受け入れ条件をすべて満たし、アーカイブの承認を得た状態。
• 未完了のまま凍結：活動中の入口からは外すが、完了とはしない。未検証の提案を事実に格上げしない。
• 明確な放棄：実施しないことと、その影響を記録する。単なる一時停止として扱わない。正式な終了状態を追加するかどうかは、別途契約を改訂して決める。

通常は活動中のエントリーポイントだけを読み、同じディレクトリにある過去の計画を毎回すべて検索する必要はありません。過去の計画の再開や確認を求められた場合に、対象を絞って探します。凍結した計画を再開する際は、改めて承認を得て、元の計画への参照を残した新しい実行用インスタンスを作り、検証し直します。以前の「問題なし」という結果をそのまま引き継いではいけません。現在のライフサイクル規則とも整合する運用です。

ファイル名の変更は保存操作であり、受け入れ条件を満たした証明ではありません。上書きを防ぎ、未完了事項を残し、参照先も適切に処理しましょう。また、固定の入口ファイルを保つためだけに空の計画テンプレートを作る必要もありません。

5. テストとコードの対応は一対一ではなく、多対多で考える

「コード1つにつきテスト1つ」という対応を強制するのはおすすめできません。ひとつのテストが複数のコンポーネントを確認することもあれば、ひとつのコンポーネントに単体テスト、プロパティテスト、統合回帰テストが必要なこともあります。

まずは、次のような方法から始めるとよいでしょう。

• tests/の中を、モジュールや責務ごとに整理する。
• 関連する仕様に、重要な不変条件、テストの入口、有界な検証コマンドを記す。
• パス同士の対応が見つけにくい場合に限り、テスト対応表のような候補ファイルを追加する。

対応表に書くのは、モジュールまたは契約の識別子、ソースの範囲、テストの範囲、検証の入口といった必要最小限にします。ディレクトリ構造全体を複製したり、テストの合否を重ねて記録したりしないようにします。

保守上のチェックは、パスとコマンドが有効であることです。対応表があるだけで、十分なテストカバレッジやテストの成功が証明されるわけではありません。ファイルの散らかりを防ごうとして、すぐ古くなる台帳を増やさないことが大切です。

6. 草稿は整理できる。ただし、信頼性は置き場所だけでは決まらない

一度きりの草稿、一時スクリプト、探索レポートを.scratch/にまとめる方針は有効です。ただし、「この中の情報は一次情報として使えない」「いつでも全部削除できる」というルールにはしないでください。

• モデルが作成した調査要約は二次的な解釈であり、それだけで事実の根拠にはできません。
• 元のテスト出力や実際の診断記録は、一時ディレクトリにあっても一次証拠になり得ます。信頼性は、出所、環境、時点、記録の完全性によって判断します。
• 計画、判断、受け入れの根拠として参照されている唯一の証拠は、安易に削除できません。整理の前に必要な原本を残すか、その証拠に依存する結論を明確に取り消します。
• 重要な発見を整理して残すときは、根拠の場所、適用範囲、未確認事項も記録します。要約によって仮説が事実に変わってはいけません。

docs/にある古いレポートやアーキテクチャ図も、古いという理由だけで一律に不要とは限りません。「現在の保守対象」「明確に履歴資料としたもの」「未確認の資料」に分けて考えます。

• 現行文書には適用範囲を明記し、関連する契約が変わったときに見直す。
• 古い図や案には「履歴」「旧版」「置き換え済み」などの位置づけを示し、現在の基準としては扱わない。
• 長期的な価値も参照関係もない作業資料は、承認を得たうえで一時領域へ移すか削除する。

保存していることと、毎回読み込むことは別です。必要な履歴を残しつつ、毎回すべてを読まずに済むよう、対象を絞った読み込みと有効性の表示でコンテキストの混雑を防ぎます。証拠を消すことを優先する必要はありません。

まとめ：整理の前に、状態と役割を分ける

この構成は、次の4つの境界を守るなら、開発資産を整理する方向として妥当です。

1. テストは集中管理を基本にしつつ、言語ごとの例外を認める。
2. 仕様は現在の契約を示し、すべてのADRの要約にはしない。
3. 凍結は未完了の状態を保つ。完了やアーカイブとは区別する。
4. 一時資料を片づけても、唯一必要な証拠は失わない。

現在の標準計画パスと許可パス、および分析モードの編集範囲は、まだ旧構成に結び付いています。今後移行する場合は、ルール、テンプレート、参照、検証、ホスト環境への適応も合わせて更新する必要があります。ディレクトリ名を変えただけで移行が完了したと見なすことはできません。

なお、今回行ったのはセッション内での整理と分析のみです。資産の書き込み、移動、凍結、削除は行っていません。