to-docs

To Docs

最近の作業を、セッションの変更履歴として扱うのではなく、長く使えるガイダンスにまとめます。

複数のリポジトリに適用できる手順は、再利用可能なスキルにまとめます。このワークフローの対象外であることを報告し、プロジェクトのルールとして文書化しないでください。

両フェーズの対象は、docs/adr/ 以外のプロジェクトガイダンスに限定します。発見、読み取り、判断の分析、文書の変更（整合性の調整や相互参照の更新を含む）において、このディレクトリとその内容をすべて除外してください。そこにのみ記録されたガイダンスは、すでに網羅されているとはみなしません。

フェーズ 1：提案

このフェーズでは、プロジェクトのドキュメントを編集しないでください。

1. リポジトリの指示と、該当するガイダンスを記載する可能性のある既存ドキュメントを読みます。コミット済みのガイダンスと、未コミットのドキュメント草稿を区別してください。作業ツリーに草稿があるというだけで、承認済みの方針として扱わないでください。
2. 会話またはユーザーが指定した作業を、権威ある対象範囲として扱います。議論、関連コード、対象を絞った差分から、その作業に関する重要な判断を再構成します。却下された代替案や後の修正から明らかになった暗黙の判断も含めてください。無関係な作業ツリーの変更は対象外とし、差分は判断を文書化するための候補一覧ではなく、根拠として使用してください。
3. 各判断を単に分類するのではなく、評価します。次の点を確認してください。
   • このガイダンスは、別のリソースやページでも役立ちますか？
   • 現在の実装を説明するのではなく、意図された不変条件を示していますか？
   • 将来のコーディングエージェントは、それを知ることで、実質的により適切な選択ができますか？
   • 対象範囲、例外、失敗ケースを明確に述べられますか？
   • たまたまの一例ではなく、繰り返しの使用や強い設計上の根拠によって裏付けられていますか？
   • すでに十分に文書化されていますか？
   • 既存のガイダンス、リンタールール、テスト、共有モジュールと矛盾していませんか？
4. 候補となるルールを反例に照らして検証します。元のケース以外では意味的に誤りとなるルールは、却下するか範囲を狭めてください。
5. 重要な判断を、次のいずれかに分類します。
   • 文書化する：長期的に有効で、一般化できるガイダンス。
   • 既存のガイダンスを改訂する：すでに記載されているが、不完全、誤解を招く、または新たな判断と矛盾している。
   • すでに網羅されている：文書の変更は不要。
   • ローカルに留める：リソース、ルート、文言、命名、実装に関する詳細。
   • 保留する：パターンとして妥当そうだが、プロジェクトのルールとするには根拠が不足している。
6. 意味のある結果だけを提示します。提案する文書変更ごとに、次の内容を含めてください。
   • 一般化したルール。
   • プロジェクト全体に適用する価値がある理由。
   • 対象範囲と例外。
   • そのルールを記載すべきドキュメント。
   • あわせて更新が必要な矛盾や関連する強制ルール。
7. プロジェクトのドキュメントに含めないと判断した重要な判断を、却下の理由とともに明示します。
8. 最後に、提案の承認を求めます。ユーザーが明示的に承認するまで、ドキュメントを編集しないでください。

判断の経緯を確認できない場合、または対象範囲を無関係な作業から確実に切り分けられない場合は、その制約を伝え、作業ツリー全体から方針を推測するのではなく、不足している確定条件や判断の背景を尋ねてください。

新しいドキュメントを作成するよりも、既存の権威あるドキュメントを優先して変更してください。同じルールを複数のドキュメントに重複して記載しないでください。ルールの全容は一つのオーナー文書に記載し、ほかの箇所では短い相互参照を使用してください。

フェーズ 2：承認後に適用

明示的な承認を得た後：

1. このフェーズ全体を通じて、/writing-for-agents を使用し、その執筆規律を適用します。利用できない場合は作業を中止し、ユーザーに npx skills@latest add mattpocock/skills --skill writing-for-agents をインストールするよう依頼します。
2. 編集する前に、影響を受けるすべてのドキュメントを読み直します。
3. 承認されたルールのみを適用し、リポジトリの用語と、言語に関する要件を維持します。
4. 対象範囲内のドキュメント一式を整合させます。古くなったガイダンスを削除し、矛盾を解消して、相互参照を更新します。
5. ドキュメントに記載されたポリシーが機械的にチェックされる場合は、リンターの設定、共有モジュール、テストなどの適用方法も更新します。ドキュメントと適用方法に食い違いを残さないでください。
6. リソース固有の例は説明用のものとして扱い、その名前、ルート、フィールド、クエリパラメーターを普遍的なポリシーにしないでください。
7. 変更したドキュメントと適用方法に応じたチェックを実行します。実行しなかったチェックは報告してください。
8. 定めた永続的なルール、そのルールを管理するドキュメント、およびコードでまだ必要な、承認済みの後続作業をまとめます。

品質基準

有用なガイドラインは、将来のエージェントに、何を選ぶべきか、その理由、適用範囲、適用すべきでない場合を伝えます。最終的なコードを言い換えるだけのルール、プロジェクトの不変条件に基づかない個人的な好みを表すルール、より長く有効な意味的ルールでなく具体的な手段を指定するルールは採用しないでください。