# Isdd Traceable Coding

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

- Skill: `notfolder/isdd-traceable-coding` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add notfolder/isdd-traceable-coding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/notfolder/isdd-traceable-coding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: notfolder (https://skillmd.com/u/notfolder)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/notfolder/isdd-traceable-coding

---


# 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` の正本更新は本スキルの責務に含めない
- 実装中に要件・設計の不足や矛盾を発見した場合は、`docs/proposals.md` に提案を追記する
- 正本更新は `isdd-post-implementation-review` が実施し、完了時に `docs/proposals.md` を削除する

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

- 削除された要件・設計に対応するコード: 完全に削除する
- 新規採番が必要になった場合: ただちにコーディングを停止し、`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. コメント付与後、要件・設計との対応漏れがないかをセルフレビューしてユーザーに報告する
10. 以下を**必ず bash で実行**して実装完了条件（docker-compose / E2E / README）を機械的に確認する
    ```bash
    python3 .agents/skills/isdd-common/scripts/implementation_completeness_checker.py .
    ```
    - 実行結果（OK/FAIL件数）を最終報告に必ず記載する
    - FAIL が1件でもある場合は**完了を報告してはならない**。FAIL項目を対処してから再実行する
    - 対処内容の例:
      - `docker-compose.yml が見つかりません` → docker-compose.yml を作成する
      - `e2e/ ディレクトリが存在しません` → E2Eテストを実装し `e2e/` に配置する
      - `README.md に不足があります` → 起動方法・初期ユーザー情報を README.md に追記する

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

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

- [ ] `trace_comment_coverage_checker.py` の実行ログをレスポンスに貼り付けた
- [ ] `rq_ds_link_checker.py` の実行ログをレスポンスに貼り付けた
- [ ] `implementation_completeness_checker.py` の実行ログをレスポンスに貼り付けた（全項目 OK であること）
- [ ] `docker-compose.yml` が存在し起動確認済みである
- [ ] E2E テストが `e2e/` 配下に存在し mock モードで全件通過している
- [ ] `README.md` に「起動方法」と「初期ユーザー」が記載されている
- [ ] 全対象要素に6ラベル（`要件ID:` / `設計ID:` / `要件概要:` / `設計概要:` / `呼び出し先設計ID:` / `呼び出し元設計ID:`）が揃っている
- [ ] `# [DS-...]` などの角括弧形式が1件もない
- [ ] `Design ID:` `Requirement ID:` などの英語ラベルが1件もない

## 実装スキルのゴール

以下の**全て**を満たすことをこの実装スキル（isdd-traceable-coding）の完了条件とする。1つでも未達の場合は完了を報告してはならない。

- `trace_comment_coverage_checker.py` でトレーサブルコメントのカバレッジが100%である
- `implementation_completeness_checker.py` の全項目（docker-compose / E2E / README）が OK である
- E2E テストを mock モードで実際に実行し、全件通過している

---

## 次のステップ

完了を報告する際に、ユーザーに次のスキルを提案する。

- `isdd-post-implementation-review` を実行して実装後の逆引き整合チェックを行い、要件・設計・コードの正本を確定する