software-lifecycle

ソフトウェアライフサイクルパック — ここでの作業方法

このプロジェクトには、エンジニアリングチームまたは OSS プロジェクト向けのドキュメントライフサイクルが含まれています。フローは 提案 → 決定 → 仕様 → 事後検証 で、ガイドはハウツーの分類です。このスキルではワークフローを定め、テンプレートとフォルダーの説明をすっきり保ちます。

このスキルはパックのガイダンスです。プラットフォームの /open-knowledge スキル（読み取り／書き込み／プレビュー／リンク／グラウンディングのルール）は、引き続きすべての Markdown 操作に適用されます。このスキルは、その上にライフサイクルの規約を重ねます。

フロー

proposals/    in-flight RFC-shape design proposals
   ↓ accepted
decisions/    frozen ADRs (the record of what was decided)
   ↓ derived
specs/        implementation specs for accepted proposals
   ↓ when things break
postmortems/  blameless incident write-ups
guides/       how-to / onboarding / runbooks (referenced throughout)

フォルダーごとのルールとエージェントの動作

proposals/ — 提案ごとに1ファイル（0001-feature-name.md）を作成します。ステータスは draft → fcp → accepted/rejected と遷移します。採択された提案は decisions/ の記録に移行します。構成：動機／設計／欠点／代替案／未解決の質問。エージェント：提案の status: draft が14日を超えて続いている場合、作成者に次へ進める、保留する、または終了するよう促します。

decisions/ — アーキテクチャ決定記録（MADR / Nygard 形式）です。採択後は凍結されます。決定ごとに1ファイル（NNNN-title.md）を作成し、ステータスは proposed/accepted/deprecated/superseded です。以前の決定に取って代わる新しい決定は、Supersedes: を使って以前の決定にリンクします。エージェント：新しい決定を追加するときは、同じサブシステムに関わる既存の記録を確認し、コミット前に Supersedes: の候補を提示します。

specs/ — 採択された提案から派生する実装仕様です。github/spec-kit 形式を推奨します。仕様ごとに1つのフォルダー（specs/NNN-name/）を作成し、spec.md + plan.md + tasks.md を格納します（このパックには3つすべてのテンプレートが含まれています）。親となる提案を参照します。エージェント：仕様が status: shipped に移行し、オーナーが仕様のサブシステムでインシデントを報告した場合、事後検証テンプレートを提案します。

postmortems/ — 非難を伴わないインシデントの振り返りです。インシデントごとに1ファイル（YYYY-MM-DD-name.md）を作成します。構成：概要／タイムライン／根本原因／うまくいったこと／アクションアイテム（Google SRE 形式）。エージェント：同じサブシステムに関わる以前の事後検証にリンクする Related: ブロックを提示します。

guides/ — ハウツーガイド、オンボーディングドキュメント、サービスに紐づく運用手順書（Diátaxis のハウツー）です。guide、onboarding-guide、runbook のテンプレートが含まれています。last_verified を記録し、定期レビューで古くなったガイドを見つけやすくします。エージェント：事後検証が公開されたら、アクションアイテムからガイド化できるフォローアップを探し、症状とタイムラインの抜粋をあらかじめ記入したガイドのひな形を作成します。

5つのワークフロー

このプロジェクトでのドキュメント作成は、慣例ではなく手順に従います。各ワークフローは個別のスキルとして提供され、作業が必要なときにだけ読み込まれます。フォルダーに一から書き始めるのではなく、タスクに合ったスキルを使ってください。

ワークフロー	関連スキル	使用する場面
提案をまとめる	/frame-a-proposal	変更を実装する前に、設計して議論する必要があるとき。
仕様を書く	/write-a-spec	採択された提案を、実装可能な仕様に落とし込む必要があるとき。
決定を記録する	/record-a-decision	決定が実際になされ、その背景と結果を記録する必要があるとき。
事後検証を書く	/write-a-postmortem	インシデントが発生し、チームが非難を伴わない振り返りを必要とするとき。
設計をレビューする	/review-a-design	既存の提案、仕様、または決定の妥当性を厳しく検証する必要があるとき。

テンプレート

write({ document: { path, template: "<name>" } }) でドキュメントを作成します。テンプレートには構造（見出しと frontmatter のひな形）のみが含まれます。各セクションの目的は上記で説明しているため、ドキュメント本文で繰り返す必要はありません。