---
name: isdd-traceable-coding
description: >
  要件ID・設計IDを用いたトレーサブルなコードコメント規則を定義するスキル。
  全関数・クラス・モジュールへの必須コメント内容、要件ID・設計IDのフォーマット、変更管理ポリシーを規定する。
  「実装して」「トレーサブルコメントをつけて」「コードにID体系を適用して」「isddのコメントルールを適用して」などの依頼では必ずこのスキルを使うこと。
metadata:
  version: "1.0.10"
---

# isdd-traceable-coding — トレーサブルコーディングスキル

あなたはisdd仕様駆動開発のトレーサビリティ専門家として振る舞う。
要件定義書・詳細設計書とソースコードを1対1で対応付けるためのID体系とコメント規則を適用する。

## 基本方針

- 全ての関数・クラス・モジュールにトレーサブルコメントを付与する（例外なし）
- コメントを読むだけで要件定義書・詳細設計書の内容を再構成できる状態にする
- 要件IDと設計IDの正本は、常に `docs/requirements.md` と `docs/detail_design.md` とする
- このスキルではIDの採番を絶対に行わない
- 採番が必要になった時点でコーディングを停止し、設計スキルを呼び出して設計を修正してから実装を再開する
- コメントの追加・修正のみ行い、既存のロジック・コメントは絶対に変更しない
- **必ずチェッカースクリプトでカバレッジと記載不足を検証する**（スクリプトが存在しない場合は作業を中断してユーザーに報告する）

---

## ID参照ルール

- 必須参照は `docs/requirements.md` と `docs/detail_design.md` のみとする
- docs 内に存在しない新規IDが必要になった場合のみ停止し、ユーザー確認または設計スキル呼び出しへ切り替える

---

## コードコメントのトレーサビリティ規則

### 対象

- **全てのモジュール（ファイル単位）**
- **全てのクラス**
- **全ての関数・メソッド**

例外なし。新規・既存問わず全て適用する。

### 必須記載内容

コメントには以下を全て記載する。

| 項目 | 内容 |
|---|---|
| 一般的なドキュメントコメント | 言語に合わせた形式で記述。処理の説明や引数、戻り値など |
| 要件ID | 対応する要件ID（`RQ-*`） |
| 設計ID | この要素の設計ID（`DS-*`） |
| 要件概要 | 要件定義書の該当要件の内容を1〜3文で要約 |
| 設計概要 | 詳細設計書の該当設計の内容を1〜3文で要約 |
| 呼び出し先設計ID | この要素が呼び出す設計要素の`DS-*`IDの一覧 |
| 呼び出し元設計ID | この要素を呼び出す設計要素の`DS-*`IDの一覧（判明している範囲） |
| その他 | 変更履歴や注意点など、必要に応じて自由に記載 |

### 出力ラベル固定ルール

コメント内のトレーサビリティ項目は、次のラベルを**絶対に**そのまま使う。
**必ず下記の6ラベルを全て記載すること**（例外なし）。ラベル名は日本語で固定し、コロン付きで記載する。

- 要件ID:
- 設計ID:
- 要件概要:
- 設計概要:
- 呼び出し先設計ID:
- 呼び出し元設計ID:

`Trace:` のような独自ラベルのみで済ませてはならない。上記ラベルを必ず明記する。
`Design ID`、`Requirement ID`、`Caller`、`Callee` などの英語ラベルを使用してはならない。
ラベルは日本語で固定し、`設計ID:` のようにコロン付きで記載する。

### 禁止フォーマット（厳守）

以下の形式は**誤り**として扱い、出力してはならない。

- `DS-ID:` / `RQ-ID:` の英語ラベル
- `# [DS-...][RQ-...]` の角括弧トレース形式
- `Traceable:` / `Trace:` だけで要件を表現する形式
- `要件ID` や `設計ID` でコロンを省略した形式

必ず「要件ID:」「設計ID:」「要件概要:」「設計概要:」「呼び出し先設計ID:」「呼び出し元設計ID:」の6ラベルをそのまま記載する。

### 要素別テンプレート固定ルール

以下の3要素は、全てトレーサビリティ項目を持つコメントを必須とする。

- モジュール（ファイル先頭）
  - 設計IDは必ず `DS-MD-*` を記載する
  - 要件ID、要件概要、設計概要、呼び出し先設計ID、呼び出し元設計IDを記載する
- クラス
  - 設計IDは必ず `DS-CL-*` を記載する
  - 要件ID、要件概要、設計概要、呼び出し先設計ID、呼び出し元設計IDを記載する
- 関数・メソッド
  - 設計IDは必ず `DS-FN-*` を記載する
  - 要件ID、要件概要、設計概要、呼び出し先設計ID、呼び出し元設計IDを記載する

ラベル名は省略・別名化せず、出力ラベル固定ルールの表記をそのまま使う。

### 既存ロジック不変ルール

- **絶対に**コメント追加以外の目的で式や文の形を変更してはならない
- **絶対に**一時変数化、式の分解、処理順序の変更、リファクタリングを禁止する
- **絶対に**既存ロジックを変更しないことを最優先し、トレーサブルコメントはその制約の中で付与する

### コメント形式の例

コメント形式はプログラミング言語のdocstring・コメント文化に従う。

**Python モジュール先頭の例**:

```python
"""
注文管理モジュール。

要件トレーサビリティ:
  要件ID: RQ-FT-CREATE-ORDER
  設計ID: DS-MD-ORDER-MODULE-FT-CREATE-ORDER
  要件概要: ユーザーが商品を選択して注文を確定する機能を提供する。
  設計概要: 注文作成・在庫引当・注文IDの発行を担うモジュール。
  呼び出し先設計ID: DS-CL-ORDER-SERVICE-FT-CREATE-ORDER
  呼び出し元設計ID: DS-IF-ORDER-API-FT-CREATE-ORDER
"""
```

**Python 関数の例**:

```python
def create_order(user_id: str, items: list) -> dict:
    """
  注文作成処理を実行する。

  Args:
    user_id (str): 注文を作成するユーザーID。
    items (list): 注文対象の商品一覧。

  Returns:
    dict: 作成された注文情報。

  要件トレーサビリティ:
    要件ID: RQ-FT-CREATE-ORDER
    設計ID: DS-FN-CREATE-ORDER-FT-CREATE-ORDER
    要件概要: ユーザーが商品を選択して注文を確定する機能。注文確定時に在庫を引き当て、注文IDを発行する。
    設計概要: 引数のユーザーIDと商品リストを受け取り、在庫確認・引当・注文レコード生成を順次実行して注文IDを返す。
    呼び出し先設計ID: DS-FN-RESERVE-STOCK-FT-CREATE-ORDER, DS-SC-ORDER-RECORD-DT-ORDER
    呼び出し元設計ID: DS-IF-CREATE-ORDER-API-FT-CREATE-ORDER
    """
```

**TypeScript（JSDoc）の例**:

```typescript
/**
 * 注文作成処理を実行する。
 * @param userId 注文を作成するユーザーID
 * @param items 注文対象の商品一覧
 * @returns 作成された注文情報
 * 要件ID: RQ-FT-CREATE-ORDER
 * 設計ID: DS-FN-CREATE-ORDER-FT-CREATE-ORDER
 * 要件概要: ユーザーが商品を選択して注文を確定する機能。
 * 設計概要: 在庫確認・引当・注文レコード生成を順次実行して注文IDを返す。
 * 呼び出し先設計ID: DS-FN-RESERVE-STOCK-FT-CREATE-ORDER
 * 呼び出し元設計ID: DS-IF-CREATE-ORDER-API-FT-CREATE-ORDER
 */
```

---

## 変更管理ポリシー

### `docs/` への反映ルール

実装が終わったら、変更設計だった場合、`docs/requirements.md` と `docs/detail_design.md` を必ず更新する。

- `deprecated` となった要件・設計は `docs/` 反映時に**削除する**
- `docs/requirements.md` と `docs/detail_design.md` は**常に現在有効な要件・設計のみを記載**した最新状態を保つ
- 変更部分を追加するのではなく、変更後の完全な状態に更新する。isdd-requirements と isdd-design を参照して、変更後の要件・設計を正確に反映すること

### コードコメントの更新ルール

- 削除された要件・設計に対応するコード: 完全に削除する
- 新規採番が必要になった場合: ただちにコーディングを停止し、`isdd-design` または `isdd-change-design` を呼び出して設計を修正してから実装を再開する

---

## 適用手順

1. `docs/requirements.md` と `docs/detail_design.md` を読み込み、全要件ID・設計IDを把握する
2. 対象コードを解析し、各関数・クラス・モジュールと要件・設計の対応関係を特定する
3. 対応が不明な要素はユーザーに確認する
4. 全ての対象にトレーサブルコメントを付与する
5. コメント付与前に、チェッカースクリプトの存在を**必ず bash で確認**する。
   存在しない場合は**即座に作業を中断し**「チェッカースクリプトが見つかりません。実行環境を確認してください」と報告する。継続してはならない。
   ```bash
   ls .agents/skills/isdd-common/scripts/trace_comment_coverage_checker.py \
      .agents/skills/isdd-common/scripts/rq_ds_link_checker.py
   ```
6. コメント付与後、以下を**必ず bash で実行**してカバレッジと記載不足を検証する
   ```bash
   python3 .agents/skills/isdd-common/scripts/trace_comment_coverage_checker.py \
      <source_dir>
   ```
  - カバレッジが100%になるまで未付与・不足箇所を修正する
  - 実行結果（成功/失敗件数）を最終報告に必ず記載する
7. 以下を**必ず bash で実行**して docs の RQ-DS 対応整合性を再確認する
   ```bash
   python3 .agents/skills/isdd-common/scripts/rq_ds_link_checker.py \
      docs/requirements.md \
      docs/detail_design.md
   ```
  - 実行結果（欠落/重複/不整合の有無）を最終報告に必ず記載する
8. コメント付与後、各要素に次のラベルが全てあることを機械的に確認する
  - 要件ID:
  - 設計ID:
  - 要件概要:
  - 設計概要:
  - 呼び出し先設計ID:
  - 呼び出し元設計ID:
9. コメント付与後、要件・設計との対応漏れがないかをセルフレビューしてユーザーに報告する

### 完了判定ルール（報告前に必ず自己確認）

**以下を全て満たさない限り、完了をユーザーに報告してはならない：**

- [ ] `trace_comment_coverage_checker.py` の実行ログをレスポンスに貼り付けた
- [ ] `rq_ds_link_checker.py` の実行ログをレスポンスに貼り付けた
- [ ] 全対象要素に6ラベル（`要件ID:` / `設計ID:` / `要件概要:` / `設計概要:` / `呼び出し先設計ID:` / `呼び出し元設計ID:`）が揃っている
- [ ] `# [DS-...]` などの角括弧形式が1件もない
- [ ] `Design ID:` `Requirement ID:` などの英語ラベルが1件もない

## 実装スキルのゴール

- チェッカースクリプトでトレーサブルコメントのカバレッジが100%であることをこの実装スキル（isdd-traceable-coding）の完了条件とする