SOP: 目に見えないナレッジをリポジトリにエンコードする

この SOP は、重要なコンテキストが Google ドキュメント、チャットスレッド、 チケット、または人の頭の中にのみ存在する場合に使用します。

目標

エージェントから見えないナレッジをコードベースで発見可能にし、 新しいセッションが事前の会話に頼らずに対応できるようにする。

トリガーシグナル

• エージェントがシステムの動作について繰り返し質問する。
• 人が「Slackでこう決めた」や「先週Xが言ったことに従って」と言う。
• レビューで、リポジトリ内に書かれていないプロダクトやセキュリティのルールが参照される。
• 新しいセッションが、すでに確定されているはずの発見作業を繰り返す。

実行 SOP

1. 目に見えないナレッジソースをリストアップする: ドキュメント、チャット、暗黙のチームルール、口頭の決定。
2. 各ソースについて確認する: これはアーキテクチャ、プロダクト動作、セキュリティポリシー、 信頼性要件、計画コンテキスト、参照資料のいずれか?
3. 該当するリポジトリ成果物にエンコードする:
   • アーキテクチャ -> ARCHITECTURE.md
   • プロダクト動作 -> docs/product-specs/
   • 設計の根拠 -> docs/design-docs/
   • 実行状態 -> docs/exec-plans/
   • 繰り返し使用される外部参照 -> docs/references/
   • 品質または信頼性の要件 -> docs/QUALITY_SCORE.md または docs/RELIABILITY.md
4. 曖昧な記述を運用上有用な表現に置き換える。
5. 古いコピーを削除または非推奨にし、リポジトリが1つの発見可能な真実を保つようにする。

良いエンコーディングのルール

• 文学的な完全さではなく、発見可能性のために書く。
• 明確なファイル名を持つ短いドキュメントを優先する。
• 関連する成果物同士をリンクする。
• 会議の議事録ではなく、持続的なルールを保存する。
• 決定が行われたのと同じセッションでリポジトリを更新する。

完了の定義

• 新しいエージェントが人間に質問せずに関連ルールを発見できる。
• 同じ事実が矛盾する複数のファイルに散らばっていない。
• 新しい成果物が、それが管理するコードやワークフローの近くに配置されている。