# ADRとDesign Docの部分再評価

2026年9月22日、`07dd7a7` のスキルでADRとDesign Docを各2反復、スキルなし／ありの計8試行で比較した。生成8件と採点4ペアはすべて成功した。意味基準の合格数はスキルなし8/20、あり17/20で、4ペアすべてでスキルありが上回った。

[全4ペアの本文と採点](comparison.html)、[集計](report.md)、[課題と採点基準](cases.json)を保存した。Pagesの紹介例は両課題の反復1であり、反復2も比較画面から確認できる。

## 実行条件

生成は `gpt-5.6-luna / low`、採点は `gpt-5.6-terra / low`、Codexは0.155.1を使った。実行コード、課題、採点基準、モデル、推論量は前回と同じ。変更後のスキルを新しくビルドし、各試行を別のDockerコンテナで実行した。生成期間は日本時間15:26:04〜15:31:35である。

`--cases adr-boundary,design-tradeoff --repeats 2` で対象を限定した。他の8課題は今回実行していない。前回の結果とは出力先を分け、合算していない。[実行計画](manifest.json)と[実行環境](runtime-lock.json)に設定と入力のハッシュを記録した。

## スキルの有無による違い

| 指標 | スキルなし | スキルあり |
|---|---:|---:|
| 生成成功 | 4/4 | 4/4 |
| 意味基準の合格 | 8/20 | 17/20 |
| 採点用lintの合格 | 0/4 | 4/4 |
| 生成のモデル呼び出し | 4 | 24 |
| 入力トークン | 23,708 | 344,185 |
| うちキャッシュ入力 | 0 | 265,814 |
| 出力トークン | 5,744 | 12,600 |

呼び出しとトークン数は生成分のみ。入力にはキャッシュ分を含み、これらの比率をそのまま料金の比率とは扱わない。

### 決定や設計を、作業の進捗から分ける

両課題・両反復とも、スキルなしは課題ID、PR番号、進捗や今週の作業を本文に残した。後から読む人は、長く参照する決定・設計と、その時点だけの作業情報を分けて読む必要がある。

スキルありは4件とも作業情報を本文から除いた。ADRでは採用状態と決定日を保ち、設計内容や理由を理解するための日付まで削っていない。Design Docでは、担当者の今週の作業に代えて、APIからDB保存までの処理を説明している。

### 資料にない実装仕様を減らす

Design Docのスキルなしは両反復とも、取込ID、結果を照会する方法、状態管理、監視項目などを追加した。追加したIDがAPI・キュー・DBの設計全体の前提となり、原資料から決まっていた仕様との境界が分からなくなっている。

スキルありは両反復とも取込IDを導入せず、保存先をキューに渡すという資料の処理を保った。また、スキルなしが入力上限へ読み替えた10MBを、取り込むファイルの大きさとして記載した。1MBはキューの制約として区別でき、実装者が不要な入力上限を設けずに方式の採否を理解できる。

ADRの反復1では、スキルなしが補った状態確認API、完成通知、受付IDの有効期限をスキルありが追加しなかった。受付IDを返すという決定と、再試行上限が未決定であることを読める。反復2は両条件とも受付IDによる状況・完成結果の確認を補っており、この改善を両反復共通の効果とは扱わない。

## 今回修正した箇所の確認

ADRのスキルあり2件は、どちらも「決定」「決定理由」「決定日」を使った。スキルなしも決定表記を使うため、この点はスキルの有無による優位ではなく、修正後の表記の確認である。

Design Docは、反復1で「スコープ」、反復2で「範囲」を使った。表記の統一は2件中1件にとどまる。反復1の「制約」、反復2の「決定事項と制約」には、いずれも1MB上限が記載された。

反復2では、スキルなしが「本Design Docでは確定しない」とした回復方法を、スキルありが「対象外とし、未決定事項として扱う」と書いた。未決定を対象外へ移す差は、採点では不合格になっていない。表記や情報の位置付けの確認は、既存5基準の合計とは分けて読む必要がある。

## 前回との比較で言えること

[前回の全件評価](../2026-09-22-readable-c9cad42/run-notes.md)から同じ2課題・2反復だけを取り出すと、意味基準はスキルなし7/20、あり17/20だった。今回は8/20、17/20であり、スキルありの合格数は同じだった。原依頼と採点基準は変えていないが、生成と採点にはばらつきがある。今回の部分評価だけから、用語修正による総合的な品質向上は判断できない。

紹介ページの注釈は同じ反復の両条件を対応させ、共通する問題の列挙を避けた。保存した原文や採点は変更していない。生成の全呼び出しログは作業領域の `.cache/benchmark-generation-adr-design-07dd7a7/` に保持している。採点のログは `.cache/benchmark-grade-adr-design-07dd7a7/` にある。