technical-debt-register

技術的負債登録簿スキル

チームまたはサービスの技術的負債登録簿を作成します。負債登録簿は不満の一覧ではありません。エンジニアリングチームが、どの負債をどの順番で返済し、どのようなリターンを見込むかを意図的に判断できるようにする、優先順位とビジネスへの影響を考慮した一覧です。

適切な負債管理とは、すべての負債をなくすことではありません。負債を可視化して担当者を明確にし、利息コストが修正コストを上回ったときに解消することです。

必要な入力

まだ提示されていない場合は、次の情報を尋ねてください。

• チームまたはサービス名 — この登録簿の対象となるチームおよび／またはサービス
• 既知の負債項目 — 既知の技術的負債の一覧。あるいは、レガシーコード、テスト不足、古い依存関係、アーキテクチャ上の近道、手作業のプロセス、可観測性の不足、セキュリティの未対応項目について尋ね、Claude に洗い出しを依頼します
• 技術スタック — 言語、フレームワーク、インフラストラクチャ（項目を適切に分類し、スコアリングするのに役立ちます）
• チームの規模とベロシティ — エンジニアの人数、およびスプリントあたりのおおよそのストーリーポイント数または日数（工数の見積もりに必要です）
• 現在の四半期／計画期間 — ロードマップを適切な期間に合わせるために必要です

出力形式

---

技術的負債登録簿：[チーム／サービス名]

チーム： [名前] | サービス： [名前] 作成者： [名前] | 最終更新日： [日付] 計画期間： [Q[X] [年]] | レビュー頻度： [月次／四半期ごと]

---

概要

[チームの現在の負債状況、主な負債カテゴリ、ビジネス上の背景を説明する2～3文。例：ベロシティが重要な成長段階にあるのか、セキュリティ負債が重要となるコンプライアンス期限が迫っているのか。]

登録簿内の項目の合計： [X] 未解決の項目： [X] 優先度が「クリティカル／高」の項目： [X] 解消に必要な工数の合計見積もり： [X ストーリーポイント／X エンジニア週]

---

負債カテゴリの定義

カテゴリ	説明	例
コード品質	動作するものの、安全に変更することが難しいコード	重複したロジック、深くネストした条件分岐、一貫性のないエラー処理、抽象化の不足
アーキテクチャ	拡張性を制限したり、結合度を高めたりする構造上の判断	分割すべきモノリス、非同期化すべき同期呼び出し、ドメイン境界の不足
テスト	回帰リスクを高めるテストカバレッジの不足	ユニットテストの不足、統合テストがない、不安定なテストスイート、テストデータ管理がない
セキュリティ	既知の脆弱性、またはセキュリティ制御の不足	CVE を含む古い依存関係、レート制限の不足、ハードコードされたシークレット、不十分な認証
依存関係	古い、またはリスクのある外部依存関係	サポート終了ライブラリ、メジャーバージョンへの更新遅延、メンテナンスが停止したパッケージ
インフラストラクチャ	信頼性または開発者の生産性を制限するインフラストラクチャ	手動のデプロイ手順、IaC がない、単一 AZ、オートスケーリングの不足
可観測性	インシデント対応を遅らせる可視性の不足	メトリクスの不足、分散トレーシングがない、ログ構造が不十分、主要な SLI のアラートがない
プロセス	手作業、またはミスが起こりやすい運用プロセス	手動の DB マイグレーション、ランブックがない、文書化されていない属人的な知識

---

負債登録簿

スコアリング方法

ビジネスへの影響（1～5）：

• 5 — 成長を妨げる、本番環境でのインシデントを引き起こす、またはコンプライアンス上のリスクを生む
• 4 — デリバリーを大幅に遅らせる、またはインシデントの発生可能性を高める
• 3 — 目に見える遅延があり、対処は可能だが積み重なっている
• 2 — 軽微な摩擦で、当面のリスクは低い
• 1 — 見た目の問題、または将来的な改善目標であり、現在のビジネスへの影響はない

解決にかかる工数（1～5、数値が小さいほど容易）：

• 1 — 0.5 日未満、エンジニア 1 名
• 2 — 0.5～2 日、エンジニア 1 名
• 3 — 3～5 日、エンジニア 1 名または少人数のペア
• 4 — 1～2 週間、チームでの連携が必要
• 5 — 2 週間超、十分な計画と調整が必要

優先度スコア = ビジネスへの影響 ×（6 − 工数） (影響が大きく、工数が少ない項目を優先します)

---

ID	項目	カテゴリ	ビジネスへの影響（1～5）	工数（1～5）	優先度スコア	ステータス	担当者
TD-001	[例：決済フローの統合テストがない]	テスト	5	3	15	未着手	[名前]
TD-002	[例：認証ライブラリがメジャーバージョン 3 つ分遅れている]	セキュリティ	5	2	20	未着手	[名前]
TD-003	[例：データベースクエリでコネクションプーリングを使用していない]	アーキテクチャ	4	2	16	未着手	[名前]
TD-004	[例：[サービス] のデプロイが手動]	インフラストラクチャ	4	3	12	対応中	[名前]
TD-005	[例：注文処理に 200 行の巨大な関数がある]	コード品質	3	3	9	未着手	[名前]
TD-006	[例：構造化ログがなく、プレーンテキストのみ]	可観測性	3	2	12	未着手	[名前]
TD-007	[例：ORM のバージョンに既知の N+1 クエリ問題がある]	依存関係	3	3	9	未着手	[名前]
TD-008	[例：[重要な運用] のランブックがない]	プロセス	3	1	15	未着手	[名前]
TD-009	[例：テストカバレッジが 34% で、実質的な安全網がない]	テスト	4	4	8	未着手	[名前]
TD-010	[例：アプリケーションコードに設定値がハードコードされている]	コード品質	2	1	10	未着手	[名前]
TD-011	[例：フェイルオーバーなしで、サービスが単一 AZ にデプロイされている]	インフラストラクチャ	5	4	10	未着手	[名前]
TD-012	[例：[エンドポイント] の P95 レイテンシーに対するアラートがない]	可観測性	4	1	20	未着手	[名前]

---

カテゴリ別内訳

Category distribution (by item count):
─────────────────────────────────────────────
Code quality     ████████░░  [X items]  ([X]%)
Architecture     ██████░░░░  [X items]  ([X]%)
Testing          █████████░  [X items]  ([X]%)
Security         ████░░░░░░  [X items]  ([X]%)
Dependencies     ███░░░░░░░  [X items]  ([X]%)
Infrastructure   ████░░░░░░  [X items]  ([X]%)
Observability    ████░░░░░░  [X items]  ([X]%)
Process          ██░░░░░░░░  [X items]  ([X]%)
─────────────────────────────────────────────

Priority distribution:
Critical (score 20–25): [X items]
High     (score 12–19): [X items]
Medium   (score  6–11): [X items]
Low      (score   1–5): [X items]

---

優先度上位 5 項目 — 解決計画

TD-XXX: [最優先項目名]

優先度スコア： [スコア] | カテゴリ： [カテゴリ] | 担当者： [名前]

問題： [この技術的負債の内容、どのように表面化しているか、現在どのような問題を引き起こしているかを、2～3 文で説明します。具体的に、実際のインシデント、遅延、リスクに言及してください。]

ビジネスへの影響： [解決しない場合に何が起こるかを記述します。インシデント、ニアミス、成長を妨げる要因などがあれば言及してください。例：「この問題により、前四半期に本番環境で 2 件のインシデントが発生し、この領域への変更時にはデバッグに約 30 分余計にかかります。」]

解決方針： [修正内容を明確に記述します。「コードを改善する」ではなく、実際に行う作業を説明してください。例：「決済処理ロジックを専用の PaymentService クラスに切り出し、カバレッジ 80% までユニットテストを作成して、3 つの呼び出し箇所を更新します。」]

手順：

1. [チケット化できる具体的な手順]
2. [チケット化できる具体的な手順]
3. [チケット化できる具体的な手順]

受け入れ条件：

• [測定可能な条件 — 例：「アプリケーションコードにハードコードされた設定値が一切残っていない」]
• [測定可能な条件 — 例：「新しいテストを含めて CI パイプラインが成功する」]
• [測定可能な条件]

工数見積もり： [X ストーリーポイント / X 日] 推奨スプリント： [第 Q[X] 四半期のスプリント [Y] / [依存関係] の完了後]

---

TD-XXX: [2 番目に優先度の高い項目名]

優先度スコア： [スコア] | カテゴリ： [カテゴリ] | 担当者： [名前]

問題： [説明]

ビジネスへの影響： [影響の説明]

解決方針： [方針の説明]

手順：

1. [手順]
2. [手順]
3. [手順]

受け入れ条件：

• [条件]
• [条件]

工数見積もり： [X ストーリーポイント / X 日] 推奨スプリント： [スプリントまたは期間]

---

TD-XXX: [3 番目に優先度の高い項目]

(上記と同じ形式で記述します)

---

TD-XXX: ［第 4 の優先項目］

(上記と同じ形式に従ってください)

---

TD-XXX: ［第 5 の優先項目］

(上記と同じ形式に従ってください)

---

負債削減ロードマップ

基本原則

• 各スプリントのキャパシティの［X%］を負債解消に割り当てます。健全なチームには 15～20% を推奨します
• セキュリティおよび依存関係の負債には、優先度スコアにかかわらず、定められた周期で対処します
• 重大な負債があるモジュールでは、その負債が今期のスプリントに予定されていない限り、新たな機能開発を行いません
• 解決せずにクローズした負債項目（受け入れ／延期）には、必ず担当者とレビュー日を設定します

四半期計画

四半期	注力分野	対象項目	推定キャパシティ	期待される成果
［Q1 年］（現在）	セキュリティ＋可観測性	TD-002, TD-012, TD-006	［X］ポイント / ［Y］エンジニア日	認証ライブラリを最新化、レイテンシーアラートを稼働、構造化ログを導入
［Q2 年］	アーキテクチャ＋信頼性	TD-003, TD-011, TD-004	［X］ポイント / ［Y］エンジニア日	コネクションプーリングを修正、マルチ AZ を導入、デプロイの自動化を完了
［Q3 年］	テストカバレッジ	TD-001, TD-009	［X］ポイント / ［Y］エンジニア日	決済フローの統合テストを稼働、全体のカバレッジを 60% 以上に
［Q4 年］	コード品質＋プロセス	TD-005, TD-008, TD-010	［X］ポイント / ［Y］エンジニア日	巨大な関数をリファクタリング、ランブックを完成、ハードコードされた設定をゼロに

スプリント配分モデル

Sprint capacity: [X] story points

Allocation:
  ├── Feature work:        [X * 0.75 = ~Y] points  (75%)
  ├── Debt resolution:     [X * 0.15 = ~Y] points  (15%)
  └── Unplanned/bugs:      [X * 0.10 = ~Y] points  (10%)

Debt items that fit in one sprint ([≤Y] points each):
  ✓ TD-002 ([X] points)
  ✓ TD-012 ([X] points)
  ✓ TD-006 ([X] points)
  ✓ TD-008 ([X] points)

Multi-sprint debt items (break into phases):
  ~ TD-001: Phase 1 ([X] pts) → Phase 2 ([X] pts)
  ~ TD-009: Requires dedicated debt sprint or pairing

---

受け入れ済み／延期した負債

現在、修正コストがビジネス価値を上回る項目は、明示的なレビュー日を設定して受け入れます。

ID	項目	延期の理由	レビュー日	担当者
TD-XXX	［項目］	［例：「現状の規模ではユーザー向けの価値がないまま、書き換えに 3 週間かかる。トラフィックが 10 倍になった時点で再検討する」］	［日付］	［名前］
TD-XXX	［項目］	［例：「依存関係に CVE があるが、Q3 まではアップグレード手段がない。WAF ルールで緩和済み」］	［日付］	［名前］

ポリシー： エンジニアリングマネージャーにエスカレーションせずに延期できるのは、各項目につき 2 回までです。

---

詳細資料

このスキルにはサポートファイルが付属しています。利用可能な場合は使用してください。

• references/debt-pricing.md — 負債の価格付け：「問題がある」を順位付け可能な数値に変える方法。出力の作成時に適用してください。上記の手法の概要では簡略化されている、評価基準と判断の要点が記載されています。
• templates/debt-entry.md — 品質ゲートをインラインで記載した、納品物の記入用テンプレート。生成を依頼するのではなく、自分で文書を作成したいユーザーに提示してください。

採点基準（0～40）

このスキルの出力は、提出前に採点してください。32 点以上が提出可能な品質です。

評価項目	0	5	10
ビジネスインパクトへの置き換え	項目がエンジニアリング用語のみで説明されている	影響は示されているが、定量化されていない	すべての項目が、エンジニア以外でも優先順位を付けられるビジネス上の言葉（リスク、生産性の低下、コスト）で評価されている
採点の一貫性	感覚で優先順位が付けられている	数式は使われているが、セキュリティ／依存関係の項目が依然として低く採点されている	数式が一貫して適用され、「技術的に見える」ことによる偏りが明示的に補正されている
解決計画の質	上位項目の対応方針が曖昧	計画はあるが、チケット化できない	上位 5 項目について、順序付けと完了の定義を含む、具体的でチケット化可能な手順がある
キャパシティの現実性	ロードマップがスプリント予算を考慮していない	配分は示されているが、実際のキャパシティを超えている	四半期ごとの配分が実際のキャパシティに収まり、受け入れ／延期した項目に担当者とレビュー日が設定されている

品質チェック

• すべての項目に担当者が明記されています — 担当者不在の負債はありません
• 優先度スコアは任意に設定せず、計算式を使って算出されています
• セキュリティおよび依存関係の項目は、「技術的な問題」に感じられるという理由で、実際のビジネスへの影響より低く評価されていません
• 上位5項目の解決計画には、具体的でチケット化できる手順が含まれています — 「テストカバレッジを改善する」のような曖昧な説明ではありません
• 四半期ロードマップでは現実的なキャパシティが割り当てられています — 負債への割り当てが、実際のスプリント予算を超えていません
• 受け入れ済み／延期された項目には、見直し日と担当者が明記されています — 永久に延期された項目はありません
• レジスターでは、負債（意図的または蓄積された近道）とバグ（意図しない欠陥）が区別されています
• 受け入れ基準を満たした場合にのみ、項目を解決済みとしてクローズしています — PR がマージされた時点ではありません

アンチパターン

• 負債項目のスコアを任意に設定しないでください — 優先度スコアは、文書化された計算式を使って算出する必要があります
• 技術的負債（意図的な近道）とバグ（意図しない欠陥）を混同しないでください — 必要な改善策はそれぞれ異なります
• セキュリティおよび依存関係の項目を、抽象的に感じられるという理由で過小評価しないでください — 実際のビジネスへの影響に基づいて評価してください
• 「永久に延期」される項目を作成しないでください — 受け入れられた項目にはすべて、見直し日と担当者が必要です
• 曖昧な説明だけの解決計画を含めないでください — 各計画には、具体的でチケット化できる手順が必要です