koleso-webestimator — AI エージェント調整型 Umbraco / .NET 向け見積もり
Umbraco/.NET Web 開発の見積もりを、AI エージェントがコードを書き、人間がレビューする 前提で算出します。
このスキルの根底にある、10 の Umbraco プロジェクト、約 300 件の実チケットから得られた最も重要な事実：
見積もりが外れる原因は、コードそのものではないことがほとんどです。 大規模作業を人間の開発者日数で見積もると、実際の約 4 倍オーバーしました。一方、"2～3 時間" の小規模チケットは 2～3 倍アンダーシュートしました。どちらの誤差も同じ原因から生じています。コード以外の作業（デプロイ、uSync インポート、環境ごとの手動手順、テストでは見えない実際の CMS 動作、QA 対応、クライアントとの確認ラウンド）が、「予備日数」として膨らませられるか、あるいは完全に抜け落ちていたのです。
そのため、ここでの見積もりはすべて 2 つの勘定 を持ちます：
- エフォート（作業時間） — 誰かが実際に作業する時間。エージェントのコーディング＋レビューに加え、縮まないバケット。
- カレンダー（経過時間） — 回答待ち、デプロイウィンドウ、QA キューの待ち時間が大半を占める実経過時間。エフォートに混ぜません。
参照ファイル（各ステップで必要に応じて読むこと）：
references/calibration.md— エージェント速度のコーディングレートと縮まないバケットのデフォルトサイズreferences/patterns.md— 一般的な Umbraco / Razor / Vue / バックオフィス作業の参考時間references/platform-risks.md— 追加のデプロイ・確認ラウンドを必要とする CMS の挙動references/honesty-rules.md— 必須ルールとエスカレーションしきい値references/output-format.md— 内部内訳とクライアント向け回答の形式references/calibration-log.md— 見積もりと実績を記録して数値を改善する方法references/review-checklist.md— レビューモード：既存の見積もりをチェックする手順
ワークフロー
ステップ 0 — 仕様書と計画書を見つけ、見積もりのベースを決定する
コードを読む前に、このタスクに関する計画文書を検索します。以下の場所を探索します：
- リポジトリ内：
spec.md、SPEC.md、docs/spec/**、docs/specs/**、docs/plans/**（ファイル名が*-plan.md、*-design.md、*-analysis.md、*-spec*.mdのもの）、docs/handover/**、docs/adr/**、およびチケットキーや機能のスラッグを含む名前のファイル。 - チケット自体：説明、添付ファイル、コメント、およびそこからリンクされている仕様ページ（例：Confluence）。
- 同じチケットに対する過去の見積もり。以前の見積もり、却下されたオプション、未解決の質問がある場合は、数値が変わります。
次に、見積もりの ベースを 1 つ選択 し、出力の先頭にそれを明記します。
A. 計画ベースの見積もり。 仕様書や機能計画書が存在する場合。
- 見つかったすべての文書を 完全に 読みます。見出しだけでなく、要件、受け入れ基準、フェーズ、ファイルリスト、未解決の質問、改訂・逸脱、レビュー決定を含みます。
- 計画のフェーズごとに 見積もります。計画に記載されているファイルリストと手順をサブタスクの骨格として使用します（ステップ 4）。
- 各仕様要件/受け入れ基準を見積もりの 1 行に対応付けます。どのフェーズでもカバーされていない要件、およびどの要件からも要求されていないフェーズがあればリストアップします。
- 計画に含まれる未解決の質問を、それぞれデフォルトの回答とともに出力の質問リストに含めます。
- 計画が古くなっていないか確認します。計画に記載されているもの（ファイル、エイリアス、ドキュメントタイプ）と現在のコードを比較します。一致しなくなった行は、黙って価格に含めるのではなく、前提条件としてフラグを立てます。
- 範囲はより狭く、信頼度はより高くなります（
references/honesty-rules.md参照）。
B. 簡易見積もり（可視範囲）。 仕様書も計画書も見つからなかった場合。
- 出力の先頭に 「仕様書または機能計画書が見つかりませんでした。これは可視範囲の簡易見積もりです。」 と明記します。どこを探したかをリストアップします。
- チケットのテキストとコードのみから見積もります。範囲は広くなり、信頼度は Medium が上限です。
- 数値を確定させるために仕様書や計画書で決めるべきこと（質問、特定できなかった影響範囲）をリストアップします。
- 次のステップとして、チケットの計画を作成し、それから再見積もりする（ベース A）ことを提案します。計画ベースの数値がどの方向に動くと予想されるか、その理由も述べます。
部分的な文書のみが存在する場合（例：仕様書はあるが計画書がない、または別のフェーズの計画書しかない）は、カバーされている部分にはベース A、残りにはベース B を使用し、各行にラベルを付けます。
また、キャリブレーションログ（references/calibration-log.md に場所の説明あり）が存在する場合は、類似の作業タイプに関する最新のエントリを読みます。
ステップ 1 — スタックを検出する
ファイル検索ツールを使用します（シェル固有のコマンドではなく、Windows で実行されることが多いため）。以下の情報を記録します。
| 探すもの | わかること |
|---|---|
*.csproj → Umbraco.Cms の PackageReference バージョン、TargetFramework | Umbraco メジャーバージョン（10/13 = AngularJS バックオフィス、14+ = Bellissima Lit/TS）と .NET バージョン |
appsettings*.json の ModelsMode、生成されたモデルフォルダ | 厳密に型指定されたモデル vs 動的な IPublishedContent |
uSync/ フォルダ + uSync 設定（ExportOnSave、ImportOnFirstBoot、無効化されたハンドラ） | スキーマ変更に環境ごとの手動インポートが必要かどうか |
App_Plugins/*/package.manifest vs umbraco-package.json + Client/ Vite プロジェクト | バックオフィス拡張の技術 |
package.json ファイル：vue、nuxt、react、lit、jquery；ビルド出力の場所 | フロントエンドの種類と、そのビルド出力がコミットされているかどうか |
SCSS コンパイラ設定、コミット済みコンパイル CSS、rtl/ltr フォルダ | スタイルパイプラインと RTL の重複 |
uSync Languages/ の言語、レイアウトの dir="rtl" | カルチャ数と RTL 検証コスト |
| テストプロジェクト（xUnit/NUnit/Playwright）、Razor がビルド時コンパイルされるかどうか | テスト成功が実際に証明するもの |
Composers/、Hangfire、Examine インデックス設定、マイグレーション、カスタム DB テーブル | バックグラウンドジョブ、検索、カスタムデータ |
| CI/デプロイファイル、ホスティングのヒント（App Service、IIS、Docker） | 環境数とデプロイが手動かどうか |
コードベースを読めない場合は、出力にその旨を明記し、すべての範囲を 2～3 倍に広げます（honesty-rules.md 参照）。
ステップ 2 — タスクに最も近いコードを読む
類似した処理を行っている、最も近い既存のドキュメントタイプ、パーシャル、コントローラ、Vue アイランド、バックオフィス要素、インポートなどを探します。それらのファイルを 2～4 つ読みます。見積もりで述べるすべての事実を、コードまたは uSync スキーマに対して検証します。 たとえば、「そのフィールドは存在しない」と書く前に、コンテンツタイプ設定を検索します。誤った主張は、クライアントとの 1 往復のコストになります。
ステップ 3 — 分類する
| 軸 | 選択肢 |
|---|---|
| 作業タイプ | references/calibration.md の表を参照（ドキュメントタイプ/スキーマ、Razor ページ vs デザイン、Vue アイランド、バックオフィス拡張、API/コントローラ、検索、バックグラウンドジョブ、クライアントデータのインポート、サードパーティ連携、アップグレード、調査、バグ） |
| 先行事例 | 高 / 中 / 低 |
| 仕様の明確さ | 明確 / 部分的 / 曖昧 |
| CMS データを書き込むか？ | コードがコンテンツ、ブロック、メディア、またはカルチャごとの値を作成、保存、または公開するかどうか |
| フロントエンドはデザインに対して？ | ピクセルチェックが必要な Figma 作業は QA ラウンドを発生させる |
| カルチャ数 × ブレークポイント | 例：3 言語（1 つは RTL）× デスクトップ/モバイル |
| 到達すべき環境 | ローカル、開発、ステージング、本番 — 各環境でどの手順が手動か |
| 外部関係者 | クライアントコンテンツ、ベンダー API、サードパーティスクリプト、他チームのパイプライン |
ステップ 4 — コーディングをエージェント速度で分解しサイジングする
計画がある場合（ベース A）、計画のフェーズが最上位のグループになり、その手順/ファイルリストがサブタスクになります。異なる内訳をでっち上げないでください。計画がない場合（ベース B）、自分で内訳を構築します。
作業を エージェント作業で 15 分～2 時間 のサブタスクに分割します。サイジングは references/patterns.md と references/calibration.md のレートから行います。次に、レビュー時間（本番コードの場合はエージェントコーディング時間の 30～50% がデフォルト、テストやスタイルの場合は少なめ）を追加します。
人間の開発者日数でコーディングサイジングを行い、後から「予備日数」を追加しないでください。 それが約 4 倍のオーバーシュートの原因です。使用している参照時間が人間時間の場合は、calibration.md の乗数で変換します。
ステップ 5 — 縮まないバケットを追加する
references/calibration.md → 「縮まないバケット」から、該当する各項目を、それ自体の行として、独自の範囲とともに追加します。
- 環境あたりの出荷オーバーヘッド（ビルド、デプロイ、uSync インポート、ディクショナリ/コンテンツ編集、再保存、スモークチェック）
- 実際の CMS 検証ラウンド（コードが CMS データを書き込む場合やランタイム動作に依存する場合）(
platform-risks.md) - オーナー/ローカル実行 + QA 引き継ぎ
- QA ラウンド（デザインに対するフロントエンド作業の場合。トリアージ、修正、「バグではない」応答を含む）
- 多言語 / RTL 検証マトリクス
- 確認ラウンド（スコープ確定前に発生が予想されるもの）
- アップグレードテール（バージョンアップグレードの場合。リグレッション実行、ランブック、リハーサル、デプロイ後修正）
- プロセスオーバーヘッド（チームがチケットごとに計画、レビュー、検証文書、引き継ぎを作成する場合）
小規模チケットの下限 を適用します。共有環境に到達する必要があるチケットは、コードが 1 行であっても、少なくとも出荷オーバーヘッドを負担します。
ステップ 6 — カレンダー時間
経過時間が何に依存するかをリストアップします。クライアントへの未解決質問、クライアントが提供する必要のあるコンテンツ、ベンダーの回答、デプロイウィンドウ、QA の可用性などです。カレンダー時間は別途提示します（例：「エフォート 2～3 時間、現実的には Q1～Q4 への回答待ちで 1～2 週間経過」）。
ステップ 7 — セルフチェック
- サブタスクの範囲が合計と一致していること。
- 分割されていないエージェント作業 2 時間超のサブタスクがないこと。
- すべての縮まないバケットを検討したこと。スキップしたものは意図的にスキップした理由を述べていること。
- 人間の開発者日数がどこにも使われておらず、全体を通して単位が時間（h）であること。
- 「存在しない」「既にサポートされている」という主張はすべてコードまたはスキーマで検証済みであること。
- 信頼度が
honesty-rules.mdの修飾子と整合していること。 - 合計 > 40 時間 → マイルストーンに分割し、それぞれを見積もること。
- ベース（計画ベース/簡易/混合）が先頭に明記されていること。計画がある場合、すべての仕様要件が 1 行に対応付けられ、すべての計画フェーズに価格が付けられていること。計画がない場合、出力にその旨が明記され、どこを探したかがリストアップされていること。
ステップ 8 — 出力
references/output-format.md を使用します。開発者向けの 内部内訳 と、クライアント向けの 回答（時間範囲の表、合計範囲、別途価格設定されたオプション、前提条件、それぞれに見積もりで仮定したデフォルト回答が付された番号付き質問、リスク、カレンダーに関する注記）。
次に、キャリブレーションログ（references/calibration-log.md）に見積もりを記録します。ユーザーの指示でログの場所が指定されている場合は自動的に、そうでなければ開始を提案します。スキルが生成した内容と、実際にクライアントに送られた内容（判明次第）をログに記録します。
モード
シングル — 上記のワークフロー。
バッチ — 仕様書、エピック、またはバックログに対して。ステップ 0～2 を 1 回実行し、その後アイテムごとにステップ 3～7 を実行します（各アイテム 2～5 サブタスク）。1 つのテーブル（アイテム、レイヤー、エフォート範囲、サイズ、信頼度、最大のリスク）と、共通の前提条件、アイテム間の依存関係、推奨順序、そしてバッチ全体で 1 回だけ 計上する縮まないバケット（1 回のデプロイ＋1 回の uSync インポートで複数アイテムを運べる場合、QA ラウンドはアイテムごとではなくページごと）を出力します。
再見積もり — クライアントが質問に回答した後、またはスコープが変更された後に使用します。差分のみを表示します（削除された行、追加された行、修正された合計、どの質問が原因か）。クライアントが質問に回答した後、数値の確認を求めてきます。差分を承認しやすくします。
レビュー — 見積もりが既に存在する場合（仕様書、計画書、チケットコメントなど）に、それをチェックするよう依頼された場合。ゼロから再見積もりはしません。references/review-checklist.md に従います。
- すべてのバージョンを収集します。コミットされた文書、クライアント向けコピー、それが引用しているコード。
- 算術をチェックし、次にベースと信頼度が honesty-rules.md に一致するかチェックします。
- 構造（レビュー分担、バケット、要件カバレッジ、オプション、デフォルト）をチェックします。
- コードとスキーマで主要な事実を再検証し、見逃しているプラットフォームリスクを探します。
- 内部修正と、クライアントが確認すべき変更を分離します。数値が変わる場合にのみ、再提示を推奨します。
キャリブレーション（較正） — 見積もりの精度を評価するよう依頼された場合（「どの程度正確だったか」「スキルをキャリブレーションして」「見積もりの振り返りを」）、または試用期間の終了時に使用します。
- キャリブレーションログ全体を読みます。クローズされた各エントリについて、実際の値とそのソース（自己申告時間、チケットのワークログ — チーム合計の場合はその旨を注記、git アクティブ日数）を入力または確認します。不足している実績は、推測せずに尋ねます。
- 作業タイプとバケットごとに、クライアントに送られた数値とスキルの数値の比率を計算します。
- 系統的なミスを見つけます。どの作業タイプ、どのバケット（QA ラウンド、出荷オーバーヘッド、検証ラウンド、確認ラウンド）、どのルール（信頼度、小規模チケット下限）が間違っていたか、そして人間による上書きが正しかった箇所。
references/calibration.md、patterns.md、platform-risks.md、またはルールに対する具体的な修正案を提案します。それぞれを正当化するログ行と関連付けます。あるタイプのデータポイントが約 3 未満の場合は、注記するだけで変更は行いません。- ユーザーが承認した修正のみを適用し、スキルの README に日付入りの変更履歴エントリを追加し、次の見積もりがどのキャリブレーションを使用するかを示す行をログに追加します。
調査 — 「○○が原因を調査」のようなチケットの場合。タイムボックスを設定し（通常 0.25～1 時間）、そのタイムボックスで何が得られるかを明記し、考えられる結果をリストアップします。「バグではない」「既に組み込まれている」「上流の CMS バグ — バージョン X を待つ」などです。これらの結果は一般的かつ低コストです。修正が確定しているかのように調査に価格を付けないでください。