naatin777/plugumi / .agents/skills/specbook-authoring
specbook-authoring
Verifieddocs/goals, requirements, architecture, designs, decisions, contracts, verification, guides 配下の Specbook 形式 Markdown/YAML ドキュメントの作成・編集・整理・手動レビュー。設計計画・機能要件・プロトコル決定・ドキュメント再構成・relation/frontmatter の確認に使う。旧Plugumi実装を既定仕様として使わない。
Specbook ドキュメント作成(手動ワークフロー)
新しいPlugumiの設計ドキュメントを Markdown + YAML frontmatter として管理する。実行中のSpecbook Pluginは不要。ドキュメントが正本であり、将来のSpecbook実装がこれを読む可能性がある。
最初に: artifact type を決める
ユーザーのタスクに該当する reference を参照する。関連する type の reference と conventions を読む。日本語の執筆・校正・レビューを行うときは必ず 日本語の執筆・レビュー規約 も読む。 ドキュメント間 relation を作る場合に限り追加の type を読む。
| Type | ディレクトリ | 答える問い | Reference |
|---|---|---|---|
goal | docs/goals/ | プロダクトはなぜ存在し、どんな状態を目指すか | goal |
requirement | docs/requirements/ | 何が満たされなければならないか | requirement |
architecture | docs/architecture/ | システム全体の境界と関係は何か | architecture |
design | docs/designs/ | 特定のrequirementをどう満たすか | design |
decision | docs/decisions/ | どの選択をし、なぜか | decision |
contract | docs/contracts/ | 外部から観測可能などのI/F・形式に合意したか | contract |
verification | docs/verification/ | 適合をどう確認するか | verification |
guide | docs/guides/ | 利用者・開発者はどう使うか | guide |
docs/designs/(複数形・artifact type)と旧来の docs/design/ ディレクトリを混同しない。現行のdecisionディレクトリとして旧 docs/adr/ を作らない。
設計調査時の原則(情報の優先順位)
設計の判断材料は次の優先順位で扱う:
- 現在の会話で明示的に決めたこと
- 本リポジトリの採用済み(accepted)文書
- 本リポジトリのdraftと未解決事項
- 旧リポジトリ(旧Plugumi/modstrata)のADR・設計文書・PR。判断理由の調査に限る
- さらに古い会話・構想
- 新リポジトリの文書を最初に確認し、
draftとacceptedを区別する - 旧ADRの
acceptedを新Plugumiの採用状態として扱わない。旧資料は「なぜそう決めたか」を調べるためのものであり、仕様の正本ではない - 仕様が決まっていない領域を、過去の案で勝手に穴埋めしない。複数の判断がある論点は日付と置き換え関係を確認する
- 会話での新しい方針と本リポジトリのdraftが異なる場合、どちらかを自動的に確定せず差分としてユーザーに提示する
- 会話や新文書で変更した方針を、旧ADRを理由に巻き戻さない
- 文章の書き直しと新しい設計判断を混同しない
ワークフロー
- コンテキストを確立する。 まずリポジトリと既存
docs/ファイルを調べる。accepted の requirement/decision と draft・deprecated を区別する。旧Plugumiリポジトリ・過去のPoC・過去の議論は検討の入力であり、今回の作り直しの拘束力ある仕様ではない。 - type と scope を選ぶ。 関心事ごとに1つの主artifactを選ぶ。小さく独立にレビューできる requirement・design を好むが、ドキュメント数を増やすためだけに分割しない。
- 書く前に関係を探す。 対象IDと現在の正本を検索する。designは既存のrequirementへのrelationを持たなければならず、verificationは既存の検証対象へのrelationを持たなければならない。必要な前提が無ければ先に作る。relation IDを捏造しない。
- 書く前に方針を確認する。 新しい設計判断・製品方針・曖昧な解釈を含む場合は、決定事項を列挙してユーザーに確認してから書く。質問回数に制限はない。推測で方向を決めず、確認なく内容を増やさない。
- ファイル名を割り当てる。 対象typeフォルダの
NNNNN-*.mdを走査し、そのフォルダ内で一意な次の5桁ID(max + 1)を選び、安定した kebab-case の slug を使う。IDはYAMLではなくファイル名から導かれる。整理のためだけに旧IDを振り直さない。 - 作成・更新する。
templates/<type>.mdから始めてプレースホルダを置き換える。意味のある節だけを残す。type・title・description・statusとそのtypeに必要な relation を埋める。明示的な合意がない限りdraftを使う。第二の正本を作らず、既存artifactを編集する。日本語は執筆・レビュー規約に従い、主語・責務・前提を明らかにし、抽象語の多用を避ける。 - 手動レビューする。 ファイル名・フォルダ・typeの一致、ID・対象type・循環、必須フィールド、references・
sources、意味の正確さ、関連ドキュメントの更新要否を確認する。conventions 参照。日本語の読みやすさを確認した後、意味・条件・規範語・未決定事項が変わっていないか再確認する。 - 変更を報告する。 作成・変更したパス、影響する relation、未解決の疑問、実行しなかったチェックを列挙する。Specbook Pluginで検証していないのに検証済みと主張しない。
やってはいけないこと
- ユーザーに確認せず、設計判断・製品方針・open questionの結論を自分で決めて書かない
- 確認のための質問を省かない(質問回数に制限はない)
- 旧ドキュメント・旧API契約・旧パッケージ境界を自動的に移植しない
- 未承認のproposalやdeprecated artifactを現行契約として扱わない
- 実装状況・計測値・承認・ソースファイル・relation ID・検証結果を捏造しない
- incoming/children/siblings/
id/updated_atをYAMLへコピーしない。incoming linkは外向きrelationから導出される - 既存の正本となるdecision・contract・ルールを繰り返す第二のドキュメントを作らず、そのIDへリンクする
sourcesを埋めるためだけに実在しないソースファイルを作らない。ソースができるまでsourcesを省略する- 通常の編集にSpecbook Pluginやカスタムスクリプトを要求しない。manual-first のskillである
type横断の作成順序
新しい機能の場合、一般的な順序は次の通り:
goal(新しく目指す状態があるなら)→ requirement → architecture(システム境界が変わるなら)→ decision(重要な選択をしたとき)→ design → contract(I/Fの仕様が要るとき)→ verification → guide(利用・開発手順が要るとき)。
これは指針であり、全変更に必須のフルセットではない。decisionがdesignに先行することもあり、I/Fはdesignを起こさずcontractとしてモデル化できる。ツリーを埋めることより正確さを優先する。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |