成果物を生成・更新する際に必ず従う横断規約集。KARURAの成果物を新規作成・更新・レビューする前に必ず参照する。
The English summary is being prepared. Showing the original description.
Run score Not tested
See how to installReview the instructions the agent will receive before you install.
本リポジトリで 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] 等の段階導入ラベルは、上流の同種ラベルと表記を揃え、上流で当該ラベルが付く項目由来のものに付与するNo reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
アクター一覧の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)に位置する成果物で、本システムに関わるすべての人間アクター(関係者)を一覧化する文書。TOGAFのActor Catalog相当。BRDの下流に位置する成果物。後続の成果物であるプロダクト要求仕様書やユーザーストーリー一覧、C4モデルレベル1、C4モデルレベル2、L1シーケンス、L2シーケンスなど、様々な成果物から参照される。BRD策定後、アクター整理の段階で呼び出す。
The English summary is being prepared. Showing the original description.
ビジネス要件定義書(BRD)の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)の中でも最上流に位置する成果物であり、ドメイン定義書・プロダクト要求仕様書(PRD)本体・ドメイン要求仕様書群すべての根拠となる業務観点の要求文書。新規プロジェクト立ち上げ時の最初の成果物作成、戦略・スコープの大きな変更、KPI見直しのタイミングで呼び出す。
The English summary is being prepared. Showing the original description.
ドメイン共通要求仕様書の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)に位置する成果物で、プロダクト要求仕様書(PRD)が方針・概念を扱うのに対し、本書は **3 ドメイン以上で横断的に効く具体的な要求(水準・方針・原則)** を集約する文書。**ドメイン要求仕様書群(個別)とは並列の関係にあり、横断的な水準・方針・原則は本書が単独で責務を持つ(=厳密な MECE。個別ドメインで言い換えない)。** 機能要求・非機能要求・UI/UX 方針・セキュリティ要求・データアクセス要求・法務/コンプライアンス要求 の各節を持つ。PRD・アクター一覧・ドメイン定義書 を上流とし、PRD策定後、ドメイン要求仕様書群(個別)の作成前に呼び出す。
The English summary is being prepared. Showing the original description.
ドメイン定義書の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)に位置する成果物で、本プロダクトを構成する業務領域(ドメイン)を網羅・分類する文書。問題空間(プロダクトが扱う業務領域)の整理であり、DDDにおけるBounded Context(解空間としての実装上の境界)とは別レイヤーで扱う。BRDの下流に位置する成果物。後続のプロダクト要求仕様書、ドメイン要求仕様書群(各ドメインごとに1つ)など、様々な成果物から参照される。BRD策定後、ドメイン整理の段階で呼び出す。
The English summary is being prepared. Showing the original description.
ドメイン要求仕様書の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)に位置する成果物で、プロダクト要求仕様書(PRD)を親文書とし、ドメイン定義書で定義された各ドメインごとに1冊作成される。**ドメイン共通要求仕様書(横断的な水準・方針・原則)とは並列の関係にあり、当該ドメイン固有の業務ルール・業務状態遷移・業務運用(イレギュラー対応)のみを扱う(共通要求と内容が重なる要求は本書に書かない=厳密な MECE)。** PRD・ドメイン定義書の策定後、ドメインごとの業務要求を具体化する段階で呼び出す。下流のユーザーストーリー一覧・ユースケース一覧・機能一覧(D2)・画面要件群(D2)・L1/L2シーケンス図の起点となる。
The English summary is being prepared. Showing the original description.
プロダクト要求仕様書(PRD)の新規作成・更新・レビューを支援する。AI駆動開発成果物フローのビジネス要求(D1)に位置する成果物で、方針・概念・体験設計・制約・受け入れ基準を扱う文書。具体的な横断要求(機能要求・非機能要求・UI/UX・セキュリティ・法務 等)は独立成果物のドメイン共通要求仕様書に集約し、PRD は要求 ID を持たない。BRD・アクター一覧・ドメイン定義書 を上流とし、BRD策定後、ドメイン共通要求仕様書の作成前に呼び出す。
The English summary is being prepared. Showing the original description.