karura-conventionslisted

# プロジェクト共通の慣習 本リポジトリで Claude を介して成果物を生成・更新する際の共通ルール。 個別の成果物固有のルール(章構成・記述粒度・上下流関係など)は `plugin/skills/<skill-name>/SKILL.md` を参照する。 ## 1. プレースホルダ書式 未確定の値・プロジェクト固有の値で置換すべき箇所は二重波括弧で囲む: ```markdown {{xxx}} ``` 成果物完成時には実プロジェクトの値で置換し、`{{` が残らない状態にする。 ## 2. HINT記法(テンプレート内の書き方ガイド) テンプレート内の記入指針は HTML コメントとして埋め込む。記入完了後は削除して構わない: ```markdown <!-- HINT: ここに何を書くかの指針 --> ``` ### 注意: HTML コメント内に `-->` を含めない HTML コメントは最初に出現する `-->` でクローズされる仕様のため、HINT 本文中に矢印記法(`-->`、`-.->` 等)を書くと、その時点でコメントが終了し、以降の文字列が本文として描画されてしまう。 Mermaid・PlantUML・シーケンス図・状態遷移図など、矢印を伴う記法を HINT 内で説明したい場合は以下のいずれかで対処する。 - 矢印記号を使わず **説明的な表現** に置き換える(例:「実線矢印」「破線矢印」) - 具体的な記法はテンプレート本体側のコードブロックに記述し、HINT 内では参照に留める ```markdown <!-- ❌ HINT 内に `-->` を直接書くと、HTMLコメントがそこで閉じる --> <!-- HINT: 凡例: - `-->`: 業務工程上の遷移 - `-.->`: 横断ドメインへの参照 --> <!-- ✅ 矢印記号を説明的に置き換え、具体記法はコードブロックに委ねる --> <!-- HINT: 凡例(具体的な記法は下記コードブロック参照): - 実線矢印: 業務工程上の遷移 - 破線矢印: 横断ドメインへの参照 --> ``` ### HINT と本文の役割分担 HINT と本文(テンプレート本体に書かれる文章・表・箇条書き 等)は役割を分けて書く。両者の内容が重なるのは設計上の不備とみなす。 | 本文の性質 | HINT の役割 | |---|---| | プレースホルダ主体(大半の章) | リッチに記述(何を書くか・典型例・境界線・代表例カテゴリ 等) | | 完全な定型文(§本書について 等) | ミニマル(置換すべきプレースホルダの示唆のみ)、または削除 | **ルール**: HINT は本文を埋める前に読むガイドであり、本文の言い直しではない。本文に書かれた内容を HINT で繰り返さない。表のセルに具体例が書かれているなら HINT で同じ具体例を列挙しない。 ## 3. 要確認マーカー(推測・仮置き箇所の明示) Claude が推測・仮置きで埋めた箇所には可視マーカーを残す。 **ブロック記法**と**インライン記法**を用途で使い分ける。 ### ブロック記法 段落全体・セクション全体に対する仮置き、または複数行の詳細説明が必要な場合に使用: ```markdown > ⚠️ **要確認**: {{確認内容 / 仮置きしている前提}} ``` ### インライン記法 テーブルセル内、文中の単一値、固有名詞ピンポイントな