成果物を生成・更新する際に必ず従う横断規約集。KARURAの成果物を新規作成・更新・レビューする前に必ず参照する。
インストールする前に、エージェントに与えられる指示の中身を確認できます。
本リポジトリで Claude を介して成果物を生成・更新する際の共通ルール。
個別の成果物固有のルール(章構成・記述粒度・上下流関係など)は plugin/skills/<skill-name>/SKILL.md を参照する。
未確定の値・プロジェクト固有の値で置換すべき箇所は二重波括弧で囲む:
{{xxx}}
成果物完成時には実プロジェクトの値で置換し、{{ が残らない状態にする。
テンプレート内の記入指針は HTML コメントとして埋め込む。記入完了後は削除して構わない:
<!-- HINT: ここに何を書くかの指針 -->
--> を含めないHTML コメントは最初に出現する --> でクローズされる仕様のため、HINT 本文中に矢印記法(-->、-.-> 等)を書くと、その時点でコメントが終了し、以降の文字列が本文として描画されてしまう。
Mermaid・PlantUML・シーケンス図・状態遷移図など、矢印を伴う記法を HINT 内で説明したい場合は以下のいずれかで対処する。
<!-- ❌ HINT 内に `-->` を直接書くと、HTMLコメントがそこで閉じる -->
<!-- HINT:
凡例:
- `-->`: 業務工程上の遷移
- `-.->`: 横断ドメインへの参照
-->
<!-- ✅ 矢印記号を説明的に置き換え、具体記法はコードブロックに委ねる -->
<!-- HINT:
凡例(具体的な記法は下記コードブロック参照):
- 実線矢印: 業務工程上の遷移
- 破線矢印: 横断ドメインへの参照
-->
HINT と本文(テンプレート本体に書かれる文章・表・箇条書き 等)は役割を分けて書く。両者の内容が重なるのは設計上の不備とみなす。
| 本文の性質 | HINT の役割 |
|---|---|
| プレースホルダ主体(大半の章) | リッチに記述(何を書くか・典型例・境界線・代表例カテゴリ 等) |
| 完全な定型文(§本書について 等) | ミニマル(置換すべきプレースホルダの示唆のみ)、または削除 |
ルール: HINT は本文を埋める前に読むガイドであり、本文の言い直しではない。本文に書かれた内容を HINT で繰り返さない。表のセルに具体例が書かれているなら HINT で同じ具体例を列挙しない。
Claude が推測・仮置きで埋めた箇所には可視マーカーを残す。 ブロック記法とインライン記法を用途で使い分ける。
段落全体・セクション全体に対する仮置き、または複数行の詳細説明が必要な場合に使用:
> ⚠️ **要確認**: {{確認内容 / 仮置きしている前提}}
テーブルセル内、文中の単一値、固有名詞ピンポイントなど、特定箇所だけを示したい場合に使用:
{{値}}【要確認】
{{値}}【要確認: 短い理由】
例:
| 申込から契約成立までのリードタイム | 5営業日以内(現行比50%短縮)【要確認】 | 業務データ分析 | 月次 |
| ケース | 記法 |
|---|---|
| 段落全体・セクション全体に対する仮置き / 複数行の説明 | ブロック記法 |
| テーブルセル内 | インライン記法 |
| 文中の特定値・固有名詞ピンポイント | インライン記法 |
両形式とも grep '要確認' で一括検出できる。
【要確認】 または 【要確認: ...】 の部分のみ削除pnpm check:markers で実行| 種類 | 置き場所 |
|---|---|
| 成果物本体 | docs/<phase>/<artifact-name>.md |
| 成果物スキル | plugin/skills/<phase>-<artifact-name>/SKILL.md |
| 成果物テンプレート | plugin/skills/<phase>-<artifact-name>/template.md |
<phase> は D0.project-management, D1.business-requirements, D2.system-requirements などのフェーズ別ディレクトリ名。
スキル名は <phase>-<artifact-kebab> 形式(例: d1-business-requirement-document)。
テンプレートはスキルと同一ディレクトリに同梱し、SKILL.md から相対参照する。本リポジトリは Claude を中核に据える前提のため、テンプレートはスキルが読み込む内部リソースとして扱う。
三者は内容を重複させず、書く場所を明確に分ける。同じ内容が二箇所に現れるのは設計上の不備とみなす。
| 置き場所 | 書くもの | 書かないもの |
|---|---|---|
| template.md | 文書の骨組みのみ — タイトル・章/表の構成(列名・並び)・プレースホルダ行。冒頭 HTML コメントは SKILL.md / karura-conventions への参照案内に留める | 振る舞いルール(埋め方・粒度・分割/集約の判断・チェック観点)、汎用規約の再掲 |
| SKILL.md | 当該成果物固有の振る舞い — 生成トリガ、input/output、記述粒度、分割/集約単位、各列の埋め方 等 | description と重複する役割/位置づけ、template に従えば自明な章構成、他成果物共通の汎用規約(下記 karura-conventions に集約) |
| karura-conventions | 全成果物横断の汎用規約 — プレースホルダ書式・HINT記法・要確認マーカー・文体・ID 表記・サイドバー登録・コミット規約 等 | 個別成果物固有のルール |
原則: テンプレートはあくまで骨組み。振る舞いの制御は SKILL.md、汎用的な話は karura-conventions に書く。判断に迷ったら「この記述は他の成果物でも成り立つか?(=karura-conventions)」「この成果物だけの振る舞いか?(=SKILL.md)」「埋めるべき器の形か?(=template.md)」で振り分ける。
SKILL.md には「その成果物を生成するために実際に必要な固有の振る舞い」だけを 最小限 に書く。書かなくても Claude が上流を読めば同じ判断をする事項や、一般的な設計慣習は書かない。各情報は一意の置き場所を持ち、本文に一度だけ現れる。
以下の章をこの順で置く。
| 章 | 書くもの |
|---|---|
| 遵守すべき重要ルール | 破ると成果物や下流が壊れる、当該成果物固有の少数のルール |
| インプットする成果物 | 上流成果物のパスと、そこから何を引くか |
| アウトプットする成果物 | 成果物のパス |
| アウトプットに使用するテンプレート | テンプレートのパス |
| 引数 | 受け取る引数とその意味。引数が無ければ章ごと置かない |
| 処理 | 生成・更新の手順と判断。分岐は「もし〜なら / そうでなく〜なら / それ以外なら」の形で書く |
| 完成時のセルフチェック | 突き合わせで確かめられる項目(網羅・参照切れ・ID 重複・プレースホルダ残存 等)だけ |
## 章構成 を設けず、SKILL は「どう埋めるか」だけを書く。docs/ 配下に新しいファイルやフォルダを追加・リネーム・削除した場合は、リポジトリ直下の sidebars.ts を必ず合わせて更新する(登録しないとドキュメントサイト上から参照できない)。
D1.business-requirements/ を新設): 新しい category ブロックを追加する。label はフェーズ名(例: D1. ビジネス要求)category の items に { type: "doc", id: "<phase>/<file-stem>", label: "<日本語タイトル>" } を追記するid は docs/ からの相対パスから拡張子を除いた値(例: D1.business-requirements/business-requirement-document)label は人間が読む日本語タイトル(例: ビジネス要件定義書)スキル経由・直接対話を問わず、Claude が docs/ を編集するすべての作業に適用される。
Claude が成果物を生成・更新する際、明示的な指示がない限り 以下のものを参照源として扱ってはならない。
成果物の本文(章導入文・前文・補足説明など読み物として続く段落)は です・ます調 で統一する。 表のセル内・箇条書きの定義/項目記述・短いラベル類は 常体(する調) を用いてよい。
| 箇所 | 文体 |
|---|---|
| 「本書について」等の前文・概要段落 | です・ます調 |
| 章の導入文・補足の説明文(リスト/表の前後にある段落) | です・ます調 |
| 表のセル内 | 常体 |
| 箇条書きの定義・項目記述 | 常体 |
| 見出し・短いラベル | 不問 |
<!-- ✅ 説明段落: です・ます調 -->
本書は、本システムに関わる全アクターを一覧化したドキュメントです。
<!-- ✅ 章の導入文: です・ます調 -->
アクターは以下3軸で分類します。
<!-- ✅ 表セル内: 常体 -->
| ACT-1 | 営業職員 | ... | 設計書作成・申込受付を実施する | ... |
<!-- ❌ 説明段落で常体 -->
本書は、本システムに関わる全アクターを一覧化したドキュメントである。
成果物の表・リスト等で各エントリに付与する ID は、先頭に 成果物略号 を冠する <成果物略号>-<カテゴリ>-<連番> 形式 とする。成果物略号を冠することで「どの成果物が振った ID か」を参照箇所だけで判別でき、下流成果物からの相互参照・トレーサビリティが容易になる。
<成果物略号>-<カテゴリ>-<連番>
PRD / BRD / ACT / DOM)。AIDD フェーズ名(D0, D1, D2 等)と衝突する単一文字は使わない<成果物略号>-<連番> とする。カテゴリに親子関係がある場合はハイフンで連結してよい(例: セキュリティ要求配下のデータアクセス要求 → DOM-COMMON-SEC-DATA-1)-。英字部はすべて大文字| 成果物 | 略号 | カテゴリ / 連番の例 |
|---|---|---|
| ビジネス要件定義書(BRD) | BRD | BRD-KPI-1 / BRD-RISK-1 等 |
| プロダクト要求仕様書(PRD) | PRD | 方針・概念・制約・受け入れ基準を扱う。原則として要求 ID は付さない(具体的な要求はドメイン共通要求仕様書・ドメイン要求仕様書群に降ろす) |
| アクター一覧 | ACT | 単一種類のためカテゴリ省略。ACT-1 |
| ドメイン定義書 | DOM | ニーモニックを連番の代わりに用いる。DOM-HEAR / DOM-APPL 等。各エントリはドメイン共通要求仕様書・ドメイン要求仕様書群の親キーとなる |
| ドメイン共通要求仕様書 | DOM-COMMON | 全ドメインに横断的に効く要求。DOM-COMMON-FR-1(機能要求)/ DOM-COMMON-NFR-1(非機能)/ DOM-COMMON-UX-1(UI/UX 方針)/ DOM-COMMON-SEC-1(セキュリティ)/ DOM-COMMON-SEC-DATA-1(データアクセス: セキュリティ要求配下の入れ子カテゴリ)/ DOM-COMMON-REG-1(法務・コンプラ) |
| ドメイン要求仕様書群(個別) | DOM-<ドメインコード> | ドメイン定義書のニーモニック(HEAR / APPL 等)を冠する。DOM-HEAR-BR-1(業務ルール)/ DOM-HEAR-IRR-1(業務運用イレギュラー)/ DOM-HEAR-DATA-1(データアクセス) 等 |
| ユーザーストーリー一覧 | US | 単一種類・通し連番。US-1, US-2, ... |
| 画面コンセプト集 | SC | SC-PR-1(体験原則)/ SC-SCENE-1(代表シーン) |
| 機能一覧 | FUNC | 単一種類・通し連番。FUNC-1, FUNC-2, ... |
| 非機能要件 | NONFUNC | 単一種類・通し連番。NONFUNC-1, NONFUNC-2, ...(FUNC と対で読めるよう、冗長でも略さない) |
| 外部システム一覧 | EXT | 単一種類・通し連番。EXT-1, EXT-2, ...(本システムが連携する外部システム/外部サービス)。C4 モデル等は本一覧の EXT-* を流用する |
ID 先頭でカテゴリ判別: ID の先頭部分を見るだけで「どのカテゴリの ID か」が分かる対称性を維持する。PRD-*(方針)/ DOM-COMMON-*(ドメイン共通要求)/ DOM-<コード>-*(ドメイン個別要求)/ BRD-*(事業要求)/ ACT-*(アクター)/ US-*(ユーザーストーリー)/ SC-*(画面コンセプト)/ FUNC-*(機能)/ NONFUNC-*(非機能)/ EXT-*(外部システム) のように、ID 体系を統一する。
他成果物の略号・カテゴリは当該成果物のテンプレート/スキルで定義する。
成果物の「関連 ID」列など、複数 ID を 1 セルに列挙する場合の表記を統一する。
〜 で圧縮: UC-1〜3(= UC-1, UC-2, UC-3)US-1, US-3, US-5US-1〜12, US-114ACT-* / UC-* / DOM-* 等)は そのまま引用 し、参照側で独自に振り直さない(二重採番の禁止)名称: ID のコロン区切り、複数は中黒で併記(例: 営業職員: ACT-1、募集人: ACT-1・ACT-2)ACT1)で記述済みの成果物は、当該成果物を次に更新する際に新形式へ寄せる(一括改名は必須としない)<!-- ✅ 成果物略号 + (カテゴリ) + 連番、英字大文字、ハイフン区切り -->
| DOM-COMMON-FR-1 | 業務通知 | ... |
| DOM-COMMON-NFR-3 | 可用性 | ... |
| DOM-HEAR-BR-1 | 意向把握項目の網羅 | ... |
| DOM-HEAR-IRR-2 | 聴取の長時間中断 | ... |
| ACT-1 | 営業職員 | ... |
| DOM-HEAR | 意向把握 | ... |
| US-1 | ... | ... |
<!-- ❌ 成果物略号なし / 小文字 / ハイフンなし -->
| FR1 | 認証 | ... |
| dom-common-fr-1 | 認証 | ... |
| HEARBR1 | 認証 | ... |
grep -oE '<成果物略号>-'(例: grep -oE 'DOM-COMMON-' / grep -oE 'DOM-HEAR-')で成果物別に ID を一括抽出できる。レイヤー単位の集計は grep -oE '^DOM-'(ドメインレイヤー全般)で取得できる。
Claude がコミットを作成する際は以下を厳守する。
コミットメッセージ(本文・フッタを含む)に、AI による生成・補助を示すトレーラーや署名を 一切付与しない。具体的には以下を含めない。
Co-Authored-By: Claude ...(および Claude/AI を示す任意の Co-Authored-By)Generated with ... / 🤖 Generated with ... 等の生成ツール表記コミットメッセージは 変更内容そのものの説明のみ で構成する。本リポジトリの既存履歴に倣い、日本語の Conventional Commits 形式(feat: / refactor: / doc: 等)を用いる。
git commit 時は 今回の作業で実際に変更したファイルのみ を明示的なパス指定でコミットする。作業ツリーに無関係な変更やステージ済みファイルがあっても巻き込まない。git commit --amend をパス指定なしで実行すると既存ステージ内容を巻き込むため、対象を限定したい場合は必ずパスを明示する。
成果物スキル(plugin/skills/<skill-name>/SKILL.md)の frontmatter description は 最小限 に保つ。description の唯一の役割は ルーティング判定(モデルが全スキルの description だけを読み比べ、どれを発火すべきか決める)であり、判定に効かない情報を盛るとノイズになって発火精度を下げる。
D2・成果物名・直近の上流成果物名)目安は 1〜3 文。
以下は SKILL.md 本文が読み込まれて初めて効くため、description には載せない。
これらは SKILL.md 本文に正規の置き場所がある(§4「SKILL.md の書き方」を参照)。description はそこへ誘導する看板であり、内容の要約ではない。
全フェーズ・全成果物の生成・更新に共通して適用する。個別成果物の SKILL.md ではこれらを再掲せず、当該成果物固有の適用(どの上流のどの章を引くか・どの列に何を書くか 等)だけを書く。
各成果物は自身のフェーズの抽象度に留まり、下流フェーズで決めるべき事項(How)を先取りしない。実装を想起させる語が出てきたら、それは下流に降ろすべき兆候。
| フェーズ | 留まるべき抽象度 | 書かない(下流の How) |
|---|---|---|
| D1(ビジネス要求) | 業務言語。システム実装を想起させる語には「業務」を冠して中立化(例: 状態遷移→業務状態遷移、例外処理→業務運用イレギュラー対応) | 機能名・画面・API・データ等のシステム/設計用語 |
| D2(システム要件) | システムが提供する機能能力(capability) | 画面名・API 名・テーブル名・カラム名・実装技術・アルゴリズム 等の D3 実装語 |
| D3(システム設計)以降 | 設計・実装の How | — |
[フェーズ2] 等の段階導入ラベルは、上流の同種ラベルと表記を揃え、上流で当該ラベルが付く項目由来のものに付与するまだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
アクター一覧の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)に位置する成果物で、本システムに関わるすべての人間アクター(関係者)を一覧化する文書。TOGAFのActor Catalog相当。BRDの下流に位置する成果物。後続の成果物であるプロダクト要求仕様書やユーザーストーリー一覧、C4モデルレベル1、C4モデルレベル2、L1シーケンス、L2シーケンスなど、様々な成果物から参照される。BRD策定後、アクター整理の段階で呼び出す。
ビジネス要件定義書(BRD)の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)の中でも最上流に位置する成果物であり、ドメイン定義書・プロダクト要求仕様書(PRD)本体・ドメイン要求仕様書群すべての根拠となる業務観点の要求文書。新規プロジェクト立ち上げ時の最初の成果物作成、戦略・スコープの大きな変更、KPI見直しのタイミングで呼び出す。
ドメイン共通要求仕様書の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)に位置する成果物で、プロダクト要求仕様書(PRD)が方針・概念を扱うのに対し、本書は **3 ドメイン以上で横断的に効く具体的な要求(水準・方針・原則)** を集約する文書。**ドメイン要求仕様書群(個別)とは並列の関係にあり、横断的な水準・方針・原則は本書が単独で責務を持つ(=厳密な MECE。個別ドメインで言い換えない)。** 機能要求・非機能要求・UI/UX 方針・セキュリティ要求・データアクセス要求・法務/コンプライアンス要求 の各節を持つ。PRD・アクター一覧・ドメイン定義書 を上流とし、PRD策定後、ドメイン要求仕様書群(個別)の作成前に呼び出す。
ドメイン定義書の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)に位置する成果物で、本プロダクトを構成する業務領域(ドメイン)を網羅・分類する文書。問題空間(プロダクトが扱う業務領域)の整理であり、DDDにおけるBounded Context(解空間としての実装上の境界)とは別レイヤーで扱う。BRDの下流に位置する成果物。後続のプロダクト要求仕様書、ドメイン要求仕様書群(各ドメインごとに1つ)など、様々な成果物から参照される。BRD策定後、ドメイン整理の段階で呼び出す。
ドメイン要求仕様書の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)に位置する成果物で、プロダクト要求仕様書(PRD)を親文書とし、ドメイン定義書で定義された各ドメインごとに1冊作成される。**ドメイン共通要求仕様書(横断的な水準・方針・原則)とは並列の関係にあり、当該ドメイン固有の業務ルール・業務状態遷移・業務運用(イレギュラー対応)のみを扱う(共通要求と内容が重なる要求は本書に書かない=厳密な MECE)。** PRD・ドメイン定義書の策定後、ドメインごとの業務要求を具体化する段階で呼び出す。下流のユーザーストーリー一覧・ユースケース一覧・機能一覧(D2)・画面要件群(D2)・L1/L2シーケンス図の起点となる。
プロダクト要求仕様書(PRD)の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)に位置する成果物で、方針・概念・体験設計・制約・受け入れ基準を扱う文書。具体的な横断要求(機能要求・非機能要求・UI/UX・セキュリティ・法務 等)は独立成果物のドメイン共通要求仕様書に集約し、PRD は要求 ID を持たない。BRD・アクター一覧・ドメイン定義書 を上流とし、BRD策定後、ドメイン共通要求仕様書の作成前に呼び出す。