slopdocs

slopdocs

計画ドキュメント、バグ調査、機能の説明資料は、作成する成果物の中で最も価値があります。コードを書くのは簡単な部分です。こうしたドキュメントがなければ、次のエージェントはゼロから始め、同じ制約を再度導き出し、毎回同じトレードオフを議論し直すことになります。

このスキルでは、ドキュメントの保存場所と、作成すべきタイミングを定めます。これはファイリングシステムであり、執筆プロセスではありません。コンテンツの作成には、ほかのスキル（brainstorming、writing-plans、systematic-debugging など）を使い、その後、slopdocs を使って保存先を決めます。

対象読者：人間ではなく、ほかのエージェント

slopdocs は、あるエージェントから次のエージェントへのメモです。簡潔で、無骨で、正確な内容にしてください。セッションのたびにゼロから再導出されるはずのコンテキストを残します。

プロジェクトには、人間向けのドキュメントもあるかもしれません。通常は docs/、README.md、Wiki、またはドキュメントサイトにあります。人間向けドキュメントは、オンボーディング、公開リファレンス、マーケティングなど、目的も文章の慣習も異なります。slopdocs はそれらの代わりにはならず、そこに保存すべきでもありません。同様に、slopdocs を docs/ やその他の人間向けの場所に書かないでください。

ユーザーが種類を指定せずに「ドキュメント」を求めた場合は、どちらを指すのか確認してください。エージェント向けの slopdocs と人間向けのドキュメントは、保存場所も読み方も大きく異なります。間違えると作業が無駄になります。簡単な確認を挟めば、誤った成果物を作らずに済みます。

規約

ドキュメントはプロジェクトルートの slopdocs/ に、次の 3 つのサブディレクトリを作成して保存します。

slopdocs/
├── features/
│   └── <feature>.md
├── bugs/
│   └── YYYYMMDD-<short-slug>.md
└── plans/
    └── YYYYMMDD-<feature>.md

slopdocs/features/<feature>.md

機能ごとに更新し続けるドキュメントを 1 つ用意します。機能の現在の動作、データモデル、主要なロジック、設計上の判断を記述します。機能に変更を加えたら更新します。

slopdocs/bugs/YYYYMMDD-<short-slug>.md

バグ調査ごとに、日付を先頭につけたファイルを 1 つ作成します。修正内容はコミット履歴に残します。ドキュメントには、遠回りした調査、誤解を招いた手掛かり、根本原因の分析といったコンテキストを残します。この情報があれば、次のエージェントが同じ調査を繰り返さずに済みます。

slopdocs/plans/YYYYMMDD-<feature>.md

計画セッションごとに、日付を先頭につけたファイルを 1 つ作成します。コードを書く前に計画を記述します。リリース後も削除せずに残してください。後から機能を理解するには、最初の計画を読むのが最も早い方法です。

機能には、更新し続けるドキュメントを 1 つ用意します。バグと計画は、その時点のスナップショットです。日付を先頭につけることで、時系列を保ち、ファイル名の重複を防ぎます。

slopdoc を書くタイミング

• 検討にかなりの時間を費やした、またはアーキテクチャ上の重要な分岐が実際にあった場合。
• バグの根本原因が自明でなく、誰かが再び遭遇する可能性が高い場合。
• 新機能を開発する場合。すでに作成した計画を保存します。
• 3 か月後には奇妙に見え、誰かが「リファクタリング」で取り除こうとしそうな判断がある場合。

省略するタイミング

• 差分自体がドキュメントになっている場合。名前変更、フォーマット変更、依存関係の更新など。
• 変更が些細で、簡単に元に戻せる場合。
• ドキュメントを書くのにコードを書くより時間がかかる場合。
• 別の slopdoc にすでに書かれていることを繰り返す場合。代わりにリンクしてください。

書き方

これは、あるエンジニアから別のエンジニアへのメモです。簡潔にまとめてください。まず判断を述べ、その後に理由を説明します。試した代替案と、うまくいかなかった理由も記録します。箇条書きが雑でも構いません。洗練されて古くなった内容より、無骨でも正確な内容のほうが優れています。

人間がざっと読むための進捗報告や要約は書かないでください。次のエージェントがすぐに読んで行動に移せるコンテキストを書いてください。

変更を加える前に

既存のドキュメントがある機能を変更する前に、関連する slopdocs を読んでください。作業対象について、更新し続けるドキュメントは slopdocs/features/、過去のコンテキストは slopdocs/plans/ を確認します。

ほかのスキルとの連携

slopdocs はファイリングシステムです。コンテンツはほかのスキルが作成します。両方が有効な場合は、ドキュメントの作成にほかのスキルのプロセスを使い、そのスキルが通常指定する場所ではなく、slopdocs のパスに保存します。

superpowers（brainstorming、writing-plans、systematic-debugging）を使う場合

ブレインストーミング／設計仕様：

• brainstorming スキルのプロセスに従って、設計仕様を作成します。
• docs/superpowers/specs/ ではなく、slopdocs/features/<feature>.md に仕様を保存します。これが継続的に更新する機能ドキュメントになります。機能の進化に合わせて更新してください。

実装計画：

• writing-plans スキルのプロセスに従って、計画を作成します。
• docs/superpowers/plans/ ではなく、slopdocs/plans/YYYYMMDD-<feature>.md に計画を保存します。
• リリース後も計画を残してください。後から機能を理解するための最短の方法です。

バグ調査：

• systematic-debugging スキルのプロセスに従って調査します。
• 調査結果を残す価値がある場合（根本原因が明白でない、複数の寄り道があった、ほかの人も同じ問題に遭遇する可能性があるなど）は、調査内容を slopdocs/bugs/YYYYMMDD-<short-slug>.md に保存します。

ドキュメントを作成するその他のスキルを使う場合

同じ方針を適用します。スキルを使って作成し、保存先には slopdocs を使います。スキルが計画を docs/plans/、.sisyphus/plans/、またはその他のパスに保存する場合は、上記のファイル名規則に従って、対応する slopdocs/ のパスに変更してください。

ほかのスキルが有効でない場合

上記の「作成方法」のガイドラインに従って、自分でドキュメントを作成します。特別な手順は必要ありません。適切なフォルダーに保存してください。