maintain-project-context

プロジェクトコンテキストの維持

このスキルには define-product が必要です。作業を始める前に、インストールされていることを確認してください。インストールされていない場合は作業を中止し、インストールコマンド npx skills@latest add toy-crane/skills --skill define-product を報告してください。プロジェクトでパッケージマネージャーのランナーが固定されている場合は、それを使用してください。

今後の作業で再利用する永続的なコンテキスト全体を、意図を持って整理してください。成果物について判断を下すことなく、現在の意味を見つけやすくします。

決定権を維持する

• ユーザーが確認した場合、その種類の決定を明示的に委任した場合、または権威あるプロジェクト資料にすでに記載されている場合に限り、その意味を適用してください。
• 古くなったドキュメントを見つけるためにリリース済みのコードを使い、意図を証明するためには使わないでください。この作業中にプロダクトコードを変更しないでください。
• 意図された意味が食い違っている場合や、リリース状況が不明確な場合は、資料を変更しないでください。続行に必要な質問をそのまま尋ねてください。ファイルの日付、実装の普及度、accepted のようなラベル、または沈黙を根拠に選択してはいけません。
• 現在の事実や決定は、それを管理する成果物にのみ保持してください。並行する要約を作成したり、同じ決定権を複数のファイルに複製したりしないでください。

永続的な情報源を確認する

存在するもの、または整理のために必要なものに限って、次の情報源を確認してください。

• アプリ全体のプロダクトの前提を記載する、ルートの PRODUCT.md。
• 現在のプロジェクト用語を記載する、ルートの GLOSSARY.md。
• docs/decisions/README.md と、関連する対象領域の契約。
• リリース済みの可能性がある作業の docs/specs/<slug>/ フォルダー。
• AGENTS.md や CLAUDE.md など、常に読み込まれるリポジトリのガイダンス。

任意のファイルがないという理由だけで何かをする必要はありません。これは、単一の新たに確定した用語、決定、またはフォローアップを段階的に記録する作業ではなく、成果物をまたいで定期的に見直す作業です。

プロダクトコンテキストを維持する

PRODUCT.md が存在する場合は、その記述を現在の明示的なプロダクト決定やその他の権威あるコンテキストと照合してください。重複した記述や古くなった記述を削除し、現在も有効な内容は維持しながら、すでに確定したプロダクトの意味を反映してください。

PRODUCT.md にはプロダクトに関する内容だけを記載してください。アプリの定義、ユーザーと利用状況、課題と代替手段、約束する変化、コアループ、アプリ全体の機能と境界、体験の原則、成功の指標、前提、未解決事項が対象です。技術スタック、アーキテクチャ、リポジトリの仕組み、画面要件、作業単位のスコープ、受け入れ基準は記載しないでください。

提案された編集によって、新たな対象ユーザー、課題、約束、コアループ、プロダクトの境界、その他のプロダクトの意図を選ぶことになる場合は、ファイルを変更せず、その意味をユーザーに確定してもらってください。ユーザーがプロダクトの前提を見直したい場合は、現在の PRODUCT.md、見つかった具体的な曖昧さ、それに依存する情報源を添えて define-product を実行してください。前提の該当部分だけを見直すようにし、更新された PRODUCT.md が返された後、この作業を再開して、残りの永続的な情報源との整合性を取ってください。

意思決定の契約を維持する

docs/decisions/ を一覧表示し、インデックスがある場合は読みます。インデックスに記載されていないファイルがないか確認し、関連する主題を現在のコンテキストおよび残っている仕様と照合します。

主題ごとに編集可能な意思決定ファイルを1つ維持します。古い意思決定ファイルを有効なフォルダーに残すのではなく、履歴には Git を使用します。複数のファイルが明確に同じ意思決定を示している場合は、最も明確で安定した主題名のもとに統合します。冗長なファイルを削除する前に、参照元のリンクをすべて更新します。

この作業で作成または編集する意思決定の契約には、それぞれ主題を示すタイトルと、以下の必須セクションを含めます。

• Decisions：現在のルールをすべて記載します。
• Why：同じ議論を繰り返さずにルールを適用するために必要な、最小限の理由を記載します。

現在の価値がある場合に限り、以下のセクションを追加します。

• Boundaries：制限または例外を記載します。
• Reconsider when：意思決定を再検討すべき具体的な条件を記載します。
• Still-rejected alternatives：将来のエージェントが再び試す可能性のある、却下済みの選択肢を記載します。
• Evidence worth preserving：再現にコストがかかる測定結果や実験を記載します。

ステータス欄、前の決定を置き換えた経緯、採用日や更新日、プルリクエストの順序、古い実装メモは削除します。日付が現在のルールを定める場合、または今後の再検討時期を示す場合は、その日付を残します。

ほかの内容を削除する前に、その内容がないことで、十分な能力を持つ将来のエージェントが同じ条件下で同じ提案、調査、実験、または失敗したアプローチを繰り返す可能性があるか検討します。可能性がある場合は、繰り返しを防ぐために必要な最短の説明を残します。重複する内容と、現実的に再発する可能性のない選択肢は削除します。

関連ファイルを維持する

• docs/decisions/README.md には、意思決定ファイルごとに次の形式の項目を1つだけ記載します：- [subject](subject.md) — Read when ...。すべてのリンクが機能するようにします。案内文には、何を決定したかではなく、いつそのファイルを開くべきかを記載します。
• GLOSSARY.md には、プロジェクトが現在使用している用語のみを残し、プロジェクト内の表現がすでに変わっている場合に限り定義を書き換えます。
• 出荷済みであると確認された docs/specs/<slug>/ は、まず再利用可能な条件を満たすすべての意思決定を、それぞれの契約に保存してからフォルダーを削除します。出荷済みか不明な場合は、そのまま残して確認を求めます。進行中の仕様では、ほかで確認済みのリンクと用語のみを更新します。
• 常時読み込まれる指示には、リポジトリーの作業ルールと意思決定インデックスへの案内を残します。無関係な指示を変更せずに、複製された意思決定や製品に関する内容を削除します。

整理に必要であれば、意思決定の契約とそのインデックスを作成、名称変更、または再構築します。サイズ目標を達成するために、無関係な主題を統合したり、必要な指示を削除したりしないでください。インデックスまたは常時読み込まれるファイルが依然として見つけにくい場合は、その理由とともに報告します。

イシュートラッカーのミラーを同期する

AGENTS.md または CLAUDE.md に ## Issue tracker セクションがある場合は、両方のファイルを読み、最初に見つかったセクションと、リンク先に詳細な規約がある場合はその規約を使用します。既存のインライン規約は引き続き有効です。セットアップスキルをインストールする必要はありません。リンク先のドキュメントを読み取れない場合は、トラッカーに関する作業がブロックされていることを報告し、リポジトリコンテキストのメンテナンスを続行します。イシューは派生した調整用の情報源として扱い、プロダクトの意味、出荷、用語、決定事項に関する権威ある情報源として扱わないでください。イシューの文面やコメントを永続的なプロジェクトコンテキストに取り込まないでください。

リモートが公開しているデフォルトブランチを解決して取得します。取得したブランチ上の docs/specs/<slug>/ フォルダーとトラッカーを比較し、現在のチェックアウトにある未マージの変更とは比較しません。各フォルダーの spec.md には、Issue: <tracker>:<id> の行で対応するイシューが1件記載されています。その ID で各イシューを取得します。フォルダーに対応するイシューを見つけるために、イシューを一覧表示したり、タイトルで検索したりしないでください。また、孤立したイシューや重複イシューを探さないでください。重複イシューの整理は担当者がトラッカー上で行います。規約に spec:<slug> というタイトルキー、Source-Issue 行、または管理対象イシューの一覧がまだ記載されている場合は、それらの操作を行わず、setup-issue-tracker を再実行するようユーザーに伝えてください。また、アクティブな spec フォルダー内の Source-Issue: を Issue: に変更するよう伝えてください。古い行は読み取りません。

デフォルトブランチ上の各 spec フォルダーについて、以下のルールを適用します。

• Issue: 行がないフォルダー、または ID でイシューを取得できないフォルダーを報告し、何も作成しません。そのフォルダーを含む次の PR でイシューが作成されます。
• 取得した spec.md に基づき、規約のマーカーで囲まれたイシューの spec セクションのみを更新します。更新対象は、最初のセクションの本文、残りのセクション見出し、フォルダーパス、Blocked by: docs/specs/<other>/ のイシュー参照です。イシューのタイトルと、本文のその他すべての部分は、担当者またはエージェントが作成したかどうかにかかわらず、そのまま保持します。
• ブロッカーの集合を、Blocked by フォルダーの Issue: 行に記載されたイシューに置き換え、担当者とオープンまたはクローズの状態を保ちながら、古い関係を削除し、不足している関係を追加します。ブロッカーのフォルダーに Issue: 行がない場合は、そのことを報告し、部分的な情報に基づいて関係を削除せず、依存するイシューのブロッカー関係の集合全体を変更しないでください。
• フォルダーが存在しないことを理由にイシューをクローズしないでください。また、フォルダーが残っていることだけを理由にクローズ済みイシューを再オープンしないでください。クローズを確定するのは、実装の提供が確認された場合、または記録されたトラッカー規約に限られます。

マージ済み PR の本文を検索し、Issue: <tracker>:<id> という完全一致の行を探します。spec フォルダーが後から削除された PR も含め、各 ID でイシューを取得します。マージ済み PR は、その差分と検証によって当該イシューの実装が提供されたと確認できる場合に限り、クローズ失敗の永続的な再試行根拠となります。Spec-Folder トレーラー、リンクされた spec PR、Issue: 行、またはフォルダーが存在しないことだけでは不十分です。オープンなイシューに対して規約のクローズ操作を再試行し、その後、状態を確認します。実装が提供されていない spec のみのマージ済み PR については、イシューをオープンのままにします。イシューに PR レビューまたは作業中を示すシグナルがまだ付いている場合は、新しい実装作業を確認してから、規約の準備完了への変更操作を行い、結果を確認します。すでに開始された作業を後戻りさせないでください。安全にクローズできず、準備完了への変更もできない場合は、欠けている PR の根拠、または失敗した操作を正確に報告します。この追跡処理は、元のマージ実行でトラッカーの失敗が報告された場合にも適用されます。スカッシュマージ後に、その実行のブランチまたはコミットのトレーラーが残っていることを前提にしないでください。

設定されたツールを利用できない場合、またはいずれかの操作が失敗した場合も、リポジトリのクリーンアップを完了し、未完了のトラッカー操作とその理由を報告して、残りのイシューの状態を次回の処理に向けて維持します。

完了

安全に解決できる対象すべてに、担当者が 1 人割り当てられ、最新の表現が 1 つ存在すること、リリースが確認済みの仕様が削除されていること、任意の最新サーフェスに既知の古い重複が残っていないこと、設定済みのトラッカーミラーが記録された操作の範囲で調整されていること、曖昧な意味が保持されていることを確認したら完了です。

変更内容、削除した内容、意図的に変更しなかった内容、更新・クローズ・未変更としたトラッカーの課題とその理由、および未解決の競合や不明確なリリースそれぞれについて必要な具体的な質問を報告してください。