adr-code-traceability

ADR コードトレーサビリティ

意思決定を追跡できるよう、コードにアーキテクチャ決定記録（ADR）への参照を追加します。言語ごとのパターンと配置ガイドラインを示します。

自己進化するスキル：このスキルは使用を通じて改善されます。手順に誤りがある場合、パラメーターにずれが生じた場合、または回避策が必要になった場合は、先送りせず、直ちにこのファイルを修正してください。実際に再現できる問題がある場合のみ更新してください。

このスキルを使用するタイミング

• ADR の実装の一環として新しいファイルを作成するとき
• 自明でない実装上の選択を記録するとき
• ユーザーが「ADR トレーサビリティ」「コード参照」「意思決定を記録」と言及したとき
• /itp:go のフェーズ 1 で、意思決定の背景をコードに追加するとき

クイックリファレンス

参照形式

ADR: {adr-id}

パスの導出：ADR: 2025-12-01-my-feature → /docs/adr/2025-12-01-my-feature.md

言語ごとのパターン（概要）

言語	新規ファイルのヘッダー	インラインコメント
Python	"""...\n\nADR: {adr-id}\n"""	# ADR: {adr-id} - reason
TypeScript	/** ... \n * @see ADR: {adr-id} */	// ADR: {adr-id} - reason
Rust	//! ...\n//! ADR: {adr-id}	// ADR: {adr-id} - reason
Go	// Package ... \n// ADR: {adr-id}	// ADR: {adr-id} - reason

詳しい例は言語ごとのパターンを参照してください。

---

配置の判断ツリー

Is this a NEW file created by the ADR?
├── Yes → Add reference in file header
└── No → Is the change non-obvious?
    ├── Yes → Add inline comment with reason
    └── No → Skip ADR reference

詳しいガイダンスは配置ガイドラインを参照してください。

---

例

新規ファイル（Python）

"""
Redis cache adapter for session management.

ADR: 2025-12-01-redis-session-cache
"""

class RedisSessionCache:
    ...

インラインコメント（TypeScript）

// ADR: 2025-12-01-rate-limiting - Using token bucket over sliding window
// for better burst handling in our use case
const rateLimiter = new TokenBucketLimiter({ rate: 100, burst: 20 });

---

参照を追加しないケース

• 変更したすべての行（トレーサビリティに価値がある箇所に限ります）
• 些細な変更（書式設定、誤字の修正）
• 標準的なパターン（よく知られた慣用表現）
• テストファイル（テスト方法が ADR による決定である場合を除く）

---

参照ドキュメント

• 言語ごとのパターン - Python、TS、Rust、Go のパターン
• 配置ガイドライン - 追加するタイミングと場所

---

トラブルシューティング

問題	原因	解決策
ADR が見つからない	パス形式が間違っている	リポジトリのルートからの相対パスを使用する
参照が表示されない	コメント構文が間違っている	言語ごとのコメント形式を確認する
参照が多すぎる	ドキュメント化しすぎている	トレーサビリティに価値がある箇所に限って追加する
ADR リンクが古い	ADR の名前が変更された	現在の ADR ファイル名に合わせてパスを更新する
フックのリマインダーが煩わしい	この変更に ADR がない	インラインの ADR コメントを追加するか、新しい ADR を作成する

実行後の振り返り

このスキルの実行後、終了する前に確認してください。

1. コマンドは成功しましたか？ — 成功していない場合は、失敗の原因となった手順またはエラーテーブルを修正してください。
2. パラメーターや出力に変更がありましたか？ — 基盤となるツールのインターフェースにずれが生じた場合は、使用例とパラメーターテーブルを実際の内容に合わせて更新してください。
3. 回避策が必要でしたか？ — 臨機応変な対応（異なるフラグ、追加手順など）が必要だった場合は、次回同じ回避策が不要になるよう、この SKILL.md を更新してください。

問題が実際に再現できる場合のみ更新してください。推測に基づく更新はしないでください。