| name | isdd-traceable-coding |
| description | 要件ID・設計IDを用いたトレーサブルなコードコメント規則を定義するスキル。 全関数・クラス・モジュールへの必須コメント内容、要件ID・設計IDのフォーマット、変更管理ポリシーを規定する。 「実装して」「トレーサブルコメントをつけて」「コードにID体系を適用して」「isddのコメントルールを適用して」などの依頼では必ずこのスキルを使うこと。
|
| license | CC-BY-4.0 |
| metadata | {"version":"v1.0.14"} |
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 モジュール先頭の例:
"""
注文管理モジュール。
要件トレーサビリティ:
要件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 関数の例:
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）の例:
変更管理ポリシー
docs/ への反映ルール
本スキルはコードコメントのトレーサビリティ整備と検証に責務を限定する。
docs/requirements.md と docs/detail_design.md の正本更新は本スキルの責務に含めない- 実装中に要件・設計の不足や矛盾を発見した場合は、
docs/proposals.md に提案を追記する
- 正本更新は
isdd-post-implementation-review が実施し、完了時に docs/proposals.md を削除する
コードコメントの更新ルール
- 削除された要件・設計に対応するコード: 完全に削除する
- 新規採番が必要になった場合: ただちにコーディングを停止し、
isdd-design または isdd-change-design を呼び出して設計を修正してから実装を再開する
適用手順
docs/requirements.md と docs/detail_design.md を読み込み、全要件ID・設計IDを把握する- 対象コードを解析し、各関数・クラス・モジュールと要件・設計の対応関係を特定する
- 対応が不明な要素はユーザーに確認する
- 全ての対象にトレーサブルコメントを付与する
- コメント付与前に、チェッカースクリプトの存在を必ず bash で確認する。
存在しない場合は即座に作業を中断し「チェッカースクリプトが見つかりません。実行環境を確認してください」と報告する。継続してはならない。
ls .agents/skills/isdd-common/scripts/trace_comment_coverage_checker.py \
.agents/skills/isdd-common/scripts/rq_ds_link_checker.py
- コメント付与後、以下を必ず bash で実行してカバレッジと記載不足を検証する
python3 .agents/skills/isdd-common/scripts/trace_comment_coverage_checker.py \
<source_dir>
- カバレッジが100%になるまで未付与・不足箇所を修正する
- 実行結果（成功/失敗件数）を最終報告に必ず記載する
- 以下を必ず bash で実行して docs の RQ-DS 対応整合性を再確認する
python3 .agents/skills/isdd-common/scripts/rq_ds_link_checker.py \
docs/requirements.md \
docs/detail_design.md
- 実行結果（欠落/重複/不整合の有無）を最終報告に必ず記載する
- コメント付与後、各要素に次のラベルが全てあることを機械的に確認する
- 要件ID:
- 設計ID:
- 要件概要:
- 設計概要:
- 呼び出し先設計ID:
- 呼び出し元設計ID:
- コメント付与後、要件・設計との対応漏れがないかをセルフレビューしてユーザーに報告する
- 以下を必ず bash で実行して実装完了条件（docker-compose / E2E / README）を機械的に確認する
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 に追記する
完了判定ルール（報告前に必ず自己確認）
以下を全て満たさない限り、完了をユーザーに報告してはならない：
実装スキルのゴール
以下の全てを満たすことをこの実装スキル（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 を実行して実装後の逆引き整合チェックを行い、要件・設計・コードの正本を確定する
