テストや文書が増えると、リポジトリが見通しにくくなり、AIエージェントに渡す情報も膨らみます。とはいえ、テストをすべて提出対象から外したり、文書を一つにまとめたりすれば解決するとは限りません。

V4で考えたいのは、成果物を単に「残す／消す」で分けることではなく、何のために作り、どこで管理し、どこまで配布し、いつモデルに読ませるかというライフサイクルです。

まず確認できたこと

今回の調査は段階的なものです。リポジトリの静的な情報、Geoffrey Huntley氏の公開記事、一部の学術資料は確認できました。一方、Python公式資料に基づく一般的なテスト配置の調査や、X、Reddit、Hacker News、Lobstersでの意見の横断確認は完了していません。したがって、これらの場で一貫した合意があるとは結論づけられません。

また、テストの再実行やGitの追跡状態の確認も行っていません。以下では、確認できた事実と、そこから導く提案を分けて記します。

テストは「長期資産」と「一時資料」を分ける

リポジトリから読み取れること

• CI設定は、集約されたテストディレクトリを利用し、設定の契約、インストール・配布、資産保護などを扱っています。見た目が雑然としているという理由だけで、これらを一時的なゴミとみなすことはできません。今回はテストを実行しておらず、個々のテストの保守価値も評価していません。
• .gitignoreは一部のサンドボックス、キャッシュ、作業用ファイルを除外していますが、タスク草稿のような資料を明示的に対象にしていません。実際に存在する草稿領域と検証出力領域も、現在のルールには記載されていません。ただし、ディレクトリがあることと、その中のファイルがGitで追跡されていることは別です。今回は追跡状態を確認していません。
• 更新処理が更新するのはリポジトリであり、配布元の収集処理が読むのは選択されたスイートです。「リポジトリを取得するとテストが見える」ことは、「テストが実行先にインストールされる」ことを意味しません。
• 配布元の収集ロジックは、スイート内の通常ファイルを再帰的に集め、プラグインの配布入力へ対応づけます。そのため、一時資料を誤ってスイート内に置けば配布対象になる可能性があります。ただし、現在その問題が実際に起きているという証拠はありません。

目的ごとの扱いを決める

成果物	バージョン管理	配置・配布の考え方
長期的な回帰テスト、契約テスト、必要な統合テスト	実装とともに管理し、保守する	言語やプロジェクトの慣習に合わせる。通常は実行時の配布物に含めない
一度限りの診断、検証スクリプト、実験用入力	原則としてローカルに置き、自動的には提出しない	許可された一時領域を使い、配布用のスイートには入れない
ログ、カバレッジ結果、実行記録	ソースコードと一緒には原則提出しない。必要な証拠は目的に応じて保存する	テストコードとは分離し、インストール対象に含めない

これは現状のルールではなく、今後の提案です。

言語ごとの慣習も無視できません。Goの公式チュートリアルでは、テストファイルをテスト対象のパッケージと同じディレクトリに置いています。15 したがって、すべてのGo単体テストを共通の外部ディレクトリに移すことを、一般原則にするべきではありません。V4にはすでに集約されたテスト配置があるため、まずはそれを活用するのが現実的です。Pythonの一般的な最適配置については、今回は公式資料の確認が足りていません。

ここで大切なのは、開発用のソースツリーを整えることと、利用者が受け取る配布物を軽くすることを区別することです。前者には言語に合ったテスト配置が関係し、後者にはインストール対象の設計が関係します。ファイルを移動するだけで両方を解決することはできません。

文書は数を減らすより、役割をそろえる

既存の成果物ルーティングでは、分析、ADR、計画、契約を区別し、置き場所が決まらない場合には確認する方針が示されています。一方、草稿のルールには別のパス規約があります。静的な情報からは、成果物のライフサイクルを定めるルールに抜けがあるとは言えますが、場当たり的なディレクトリ作成が毎回起きている理由までは断定できません。

新しいディレクトリを次々に増やすのではなく、既存の構造を使いながら、文書の役割を明確にするのがよさそうです。

• 正式な分析資料：根拠、比較、反証、未確認事項を記録する。通常の相談は会話内で完結させ、保存する必要がなければ報告書を作らない。
• ADR（アーキテクチャ上の重要な決定記録）：重要な決定と、その理由・制約を残す。分析の全文や作業の逐次記録を複製しない。
• 実施計画：承認の有無、対象範囲、依存関係、受け入れ条件を記す。関連する決定を参照し、調査内容を重複して書かない。
• 一時資料：草稿、診断用入力、未加工の出力は、許可された一時領域に集める。タイトルに「草稿」とあるだけで正式な分析資料の置き場に入れない。
• 長期的な運用文書：繰り返し使える手順書として役立つ場合に保存する。一度のデプロイ作業をしただけで、新しいデプロイ用ディレクトリを自動作成しない。

文書の数、Gitに提出するかどうか、配布物に含めるかどうか、モデルに読ませるかどうかは、それぞれ別に判断します。「すべてを一つのディレクトリに入れる」ことは、ライフサイクル管理の代わりにはなりません。

Geoffrey Huntley氏の記事から読み取れること

Huntley氏の「back pressure」に関する記事は、エージェントの周囲に自動化された品質・正確性のフィードバックを設ける考え方を示しています。テストファイルを不要なノイズとして削除すべきだ、という主張ではありません。12

また、コードを別言語へ移植する方法の記事では、テストの振る舞いを仕様文書に整理し、それを移植の指針にする手順が提案されています。14 これは特定の移植作業についての方法であり、「すべてのプロジェクトでテストを文書に置き換えるべきだ」と示すものではありません。

V4に活かせるのは、実行可能な品質フィードバックを残しつつ、重複した検証資産や一度限りの資料を減らすことです。仕様は期待する振る舞いを説明し、テストはそれに対する実行可能な反証を与えます。評価せずに両者を置き換えるべきではありません。

Huntley氏がテストの提出方針、草稿ディレクトリ、配布物からの除外基準を一貫して定めているかどうかは、今回の情報からは確認できません。また、前述のオンラインコミュニティで意見が一致しているかどうかも、確認できていません。

文書の肥大化には、モデルが読む範囲で対処する

長文脈に関する研究では、モデルが入力の中ほどにある情報をうまく活用できない「lost in the middle」の課題が論じられています。3 HELMETも、長文脈モデルの性能を評価するには、単純な情報検索だけではなく、多様なタスクを含める必要があると指摘しています。4

ただし、これらの研究から「ファイルが一定の行数を超えると幻覚が起きる」とは言えません。現在のV4にどの程度のリスクがあるかも、今回の資料だけでは数値化できません。

運用上は、次のような工夫が考えられます。

• 一つの総合文書を際限なく長くするのではなく、テーマや意思決定の単位で分ける。
• 既定では現在の作業に関係する箇所を読み、過去の資料は必要に応じて参照する。
• 短い要約には根拠の場所、未確認事項、未完了の義務を残し、原資料は追跡可能な形で保管する。
• 索引は道案内に徹し、本文を複製して「第二の事実台帳」にしない。
• ログや過去の報告書を、モデルに毎回全文読ませる前提にしない。

V4で優先したい、最小限の改善

重い新規プロセスを増やすより、成果物を作るところから渡すところまでをつなぐルールを設けるのがよさそうです。

1. 作成前：何のための成果物かを確認し、既存のテストや文書を拡張できないか検討する。変更のたびに新しいファイルを作ることを機械的なルールにしない。
2. 保存前：許可された保存先、長期か一時か、バージョン管理の対象か、配布対象かを決める。判断がつかなければ独自のディレクトリを作らない。
3. 提出前：一時的な出力、機密情報、重複したテストや文書を確認する。整理のためにテストをすべて無視するのは避ける。
4. 配布前：インストール対象の境界を明確にし、一時資料がスイートに混入しないようにする。その際、要約、識別情報、資産保護に必要な既存機能を簡略化の名のもとに外さない。
5. 削除前：失敗の証拠、進行中のタスク、過去の参照関係を保護する。タスクの完了や資料の古さだけを削除許可とみなさない。

現時点の判断としては、まず一時資料と配布対象の境界を明確にし、次に文書の役割と必要に応じた読み込み方を整えるのが妥当です。Goの単体テストを全面的に移動すること、長期テストの提出をやめること、文書をすべて一つにまとめることを支持する根拠は、今回の調査では得られていません。

今後、承認を得て変更する場合は、テストの収集が失われていないこと、関連するCIが動作すること、配布物に一時資料が混入しないこと、過去の参照や未完了事項を追跡できることを確認する必要があります。

今回は会話内での調査結果の共有にとどまり、ファイルの書き込み、端末やテストの実行、整理作業は行っていません。既存の作業計画を再開・推進したものでもありません。

テストや文書が増えると、リポジトリが見通しにくくなり、AIエージェントに渡す情報も膨らみます。とはいえ、テストをすべて提出対象から外したり、文書を一つにまとめたりすれば解決するとは限りません。

V4で考えたいのは、成果物を単に「残す／消す」で分けることではなく、何のために作り、どこで管理し、どこまで配布し、いつモデルに読ませるかというライフサイクルです。

まず確認できたこと

今回の調査は段階的なものです。リポジトリの静的な情報、Geoffrey Huntley氏の公開記事、一部の学術資料は確認できました。一方、Python公式資料に基づく一般的なテスト配置の調査や、X、Reddit、Hacker News、Lobstersでの意見の横断確認は完了していません。したがって、これらの場で一貫した合意があるとは結論づけられません。

また、テストの再実行やGitの追跡状態の確認も行っていません。以下では、確認できた事実と、そこから導く提案を分けて記します。

テストは「長期資産」と「一時資料」を分ける

リポジトリから読み取れること

• CI設定は、集約されたテストディレクトリを利用し、設定の契約、インストール・配布、資産保護などを扱っています。見た目が雑然としているという理由だけで、これらを一時的なゴミとみなすことはできません。今回はテストを実行しておらず、個々のテストの保守価値も評価していません。
• .gitignoreは一部のサンドボックス、キャッシュ、作業用ファイルを除外していますが、タスク草稿のような資料を明示的に対象にしていません。実際に存在する草稿領域と検証出力領域も、現在のルールには記載されていません。ただし、ディレクトリがあることと、その中のファイルがGitで追跡されていることは別です。今回は追跡状態を確認していません。
• 更新処理が更新するのはリポジトリであり、配布元の収集処理が読むのは選択されたスイートです。「リポジトリを取得するとテストが見える」ことは、「テストが実行先にインストールされる」ことを意味しません。
• 配布元の収集ロジックは、スイート内の通常ファイルを再帰的に集め、プラグインの配布入力へ対応づけます。そのため、一時資料を誤ってスイート内に置けば配布対象になる可能性があります。ただし、現在その問題が実際に起きているという証拠はありません。

目的ごとの扱いを決める

成果物	バージョン管理	配置・配布の考え方
長期的な回帰テスト、契約テスト、必要な統合テスト	実装とともに管理し、保守する	言語やプロジェクトの慣習に合わせる。通常は実行時の配布物に含めない
一度限りの診断、検証スクリプト、実験用入力	原則としてローカルに置き、自動的には提出しない	許可された一時領域を使い、配布用のスイートには入れない
ログ、カバレッジ結果、実行記録	ソースコードと一緒には原則提出しない。必要な証拠は目的に応じて保存する	テストコードとは分離し、インストール対象に含めない

これは現状のルールではなく、今後の提案です。

言語ごとの慣習も無視できません。Goの公式チュートリアルでは、テストファイルをテスト対象のパッケージと同じディレクトリに置いています。15 したがって、すべてのGo単体テストを共通の外部ディレクトリに移すことを、一般原則にするべきではありません。V4にはすでに集約されたテスト配置があるため、まずはそれを活用するのが現実的です。Pythonの一般的な最適配置については、今回は公式資料の確認が足りていません。

ここで大切なのは、開発用のソースツリーを整えることと、利用者が受け取る配布物を軽くすることを区別することです。前者には言語に合ったテスト配置が関係し、後者にはインストール対象の設計が関係します。ファイルを移動するだけで両方を解決することはできません。

文書は数を減らすより、役割をそろえる

既存の成果物ルーティングでは、分析、ADR、計画、契約を区別し、置き場所が決まらない場合には確認する方針が示されています。一方、草稿のルールには別のパス規約があります。静的な情報からは、成果物のライフサイクルを定めるルールに抜けがあるとは言えますが、場当たり的なディレクトリ作成が毎回起きている理由までは断定できません。

新しいディレクトリを次々に増やすのではなく、既存の構造を使いながら、文書の役割を明確にするのがよさそうです。

• 正式な分析資料：根拠、比較、反証、未確認事項を記録する。通常の相談は会話内で完結させ、保存する必要がなければ報告書を作らない。
• ADR（アーキテクチャ上の重要な決定記録）：重要な決定と、その理由・制約を残す。分析の全文や作業の逐次記録を複製しない。
• 実施計画：承認の有無、対象範囲、依存関係、受け入れ条件を記す。関連する決定を参照し、調査内容を重複して書かない。
• 一時資料：草稿、診断用入力、未加工の出力は、許可された一時領域に集める。タイトルに「草稿」とあるだけで正式な分析資料の置き場に入れない。
• 長期的な運用文書：繰り返し使える手順書として役立つ場合に保存する。一度のデプロイ作業をしただけで、新しいデプロイ用ディレクトリを自動作成しない。

文書の数、Gitに提出するかどうか、配布物に含めるかどうか、モデルに読ませるかどうかは、それぞれ別に判断します。「すべてを一つのディレクトリに入れる」ことは、ライフサイクル管理の代わりにはなりません。

Geoffrey Huntley氏の記事から読み取れること

Huntley氏の「back pressure」に関する記事は、エージェントの周囲に自動化された品質・正確性のフィードバックを設ける考え方を示しています。テストファイルを不要なノイズとして削除すべきだ、という主張ではありません。12

また、コードを別言語へ移植する方法の記事では、テストの振る舞いを仕様文書に整理し、それを移植の指針にする手順が提案されています。14 これは特定の移植作業についての方法であり、「すべてのプロジェクトでテストを文書に置き換えるべきだ」と示すものではありません。

V4に活かせるのは、実行可能な品質フィードバックを残しつつ、重複した検証資産や一度限りの資料を減らすことです。仕様は期待する振る舞いを説明し、テストはそれに対する実行可能な反証を与えます。評価せずに両者を置き換えるべきではありません。

Huntley氏がテストの提出方針、草稿ディレクトリ、配布物からの除外基準を一貫して定めているかどうかは、今回の情報からは確認できません。また、前述のオンラインコミュニティで意見が一致しているかどうかも、確認できていません。

文書の肥大化には、モデルが読む範囲で対処する

長文脈に関する研究では、モデルが入力の中ほどにある情報をうまく活用できない「lost in the middle」の課題が論じられています。3 HELMETも、長文脈モデルの性能を評価するには、単純な情報検索だけではなく、多様なタスクを含める必要があると指摘しています。4

ただし、これらの研究から「ファイルが一定の行数を超えると幻覚が起きる」とは言えません。現在のV4にどの程度のリスクがあるかも、今回の資料だけでは数値化できません。

運用上は、次のような工夫が考えられます。

• 一つの総合文書を際限なく長くするのではなく、テーマや意思決定の単位で分ける。
• 既定では現在の作業に関係する箇所を読み、過去の資料は必要に応じて参照する。
• 短い要約には根拠の場所、未確認事項、未完了の義務を残し、原資料は追跡可能な形で保管する。
• 索引は道案内に徹し、本文を複製して「第二の事実台帳」にしない。
• ログや過去の報告書を、モデルに毎回全文読ませる前提にしない。

V4で優先したい、最小限の改善

重い新規プロセスを増やすより、成果物を作るところから渡すところまでをつなぐルールを設けるのがよさそうです。

1. 作成前：何のための成果物かを確認し、既存のテストや文書を拡張できないか検討する。変更のたびに新しいファイルを作ることを機械的なルールにしない。
2. 保存前：許可された保存先、長期か一時か、バージョン管理の対象か、配布対象かを決める。判断がつかなければ独自のディレクトリを作らない。
3. 提出前：一時的な出力、機密情報、重複したテストや文書を確認する。整理のためにテストをすべて無視するのは避ける。
4. 配布前：インストール対象の境界を明確にし、一時資料がスイートに混入しないようにする。その際、要約、識別情報、資産保護に必要な既存機能を簡略化の名のもとに外さない。
5. 削除前：失敗の証拠、進行中のタスク、過去の参照関係を保護する。タスクの完了や資料の古さだけを削除許可とみなさない。

現時点の判断としては、まず一時資料と配布対象の境界を明確にし、次に文書の役割と必要に応じた読み込み方を整えるのが妥当です。Goの単体テストを全面的に移動すること、長期テストの提出をやめること、文書をすべて一つにまとめることを支持する根拠は、今回の調査では得られていません。

今後、承認を得て変更する場合は、テストの収集が失われていないこと、関連するCIが動作すること、配布物に一時資料が混入しないこと、過去の参照や未完了事項を追跡できることを確認する必要があります。

今回は会話内での調査結果の共有にとどまり、ファイルの書き込み、端末やテストの実行、整理作業は行っていません。既存の作業計画を再開・推進したものでもありません。