improve-codebase-architecture (mattpocock/skills)
既存のコードベースでモジュールを深める余地を見つけ、より明確でテストしやすいインターフェースを計画します。
improve-codebase-architecture：プレーン 3.2 に対して 4.1/5。ただし、一文プロンプトはスキルのトークンの 58% で 3.9 に達します。
Codex CLI · gpt-6-astra
23.0 / 30
スキルなしに対するリフト：+0.92 · 状況次第 · 18 実行
状況次第：リフト +0.92 が +1.0 未満。推奨には合計 22/30、出力品質 3.5、リフト +1.0 が必要です。
SOTA
合格Codex でテスト済み。
カバー対象 Codex, Claude Code
Codex CLI 0.166（SOTA ティア）：採点対象 18 実行。当ティアのルールでは、ここでの合格は Claude Code もカバーします。第2ティアについては何も述べません。
スコア
各ディメンションは 0〜5 点で、6 つの合計が 30 点満点の合計スコアになります。すべてのディメンションで 5 が最良です。コスト 5 は低コストで高速、インストール 5 は簡単であることを意味します。
- トリガーの信頼性
- 5.0
- スキルなしに対するリフト
- 2.9
- 出力品質
- 4.1
- トークンと時間のコスト
- 2.0
- インストールと移植性
- 4.0
- 安全性
- 5.0
セキュリティレビュー
安全静的スキャン：CRITICAL 0 / HIGH 0 / MEDIUM 0。手動レビュー：ネットワーク無効のサンドボックスで実行しても安全（指摘なし）。クリーンなスキャン結果はスキルの安全性を証明しません。
インストール
npx skills@latest add mattpocock/skills --skill improve-codebase-architecture
固定コミット: 4ae2317ddb22b046e26455e4f9c9b3aaaf62212d
テスト済み: 2026-11-02
テスト内容
- リポジトリ全体のアーキテクチャスキャン — この小規模ショップバックエンドをアーキテクチャ改善の観点でレビューしてください。どこを再構成すればコードが変更しやすく、テストしやすくなりますか。調査結果を、このフォルダー内の report.html という名前の自己完結型 HTML レポートとして書いてください（ブラウザを開いたりサーバーを起動したりしないでください）。
- 決済と在庫のみ — このバックエンドの決済と在庫の部分だけを見て、どの再構成が効果的かを教えてください。調査結果を、このフォルダー内の report.html という名前の自己完結型 HTML レポートとして書いてください（ブラウザを開いたりサーバーを起動したりしないでください）。コードは変更しないでください。
- place_order のテストがつらい理由 — このバックエンドの place_order に対して適切なテストを書くのが苦痛に感じます。なぜでしょうか。また、どの再構成がそれを解決しますか。ファイルは変更せず、最終メッセージで回答してください。
長所
- スキルなしと比べ平均スコアを 3.2 から 4.12 に引き上げ（+0.92）。
- スキルは名前を出さずとも採用されました：スキルあり群 6/6 実行でスキルファイルが読み込まれました。
短所
- スキルなしの 1.8 倍のトークンを消費。
- タスク・群ごとに n=2。1 ポイント未満の差はノイズです。
レビュー
専用の Windows テスト PC 上で Codex CLI 0.166（gpt-6-astra、低推論）、実行ごとに新規の一時プロジェクトと一時 HOME/TMPDIR/キャッシュを使用、スキルをインストール（スキルあり群）、スキルなし（対照群）、またはスキルの中核要件をプロンプト末尾に付けた一文に圧縮（一文プロンプト群）、タスクごとに各群 2 実行、ネットワーク無効、/tmp への書き込みはブロック。プロンプトはスキル名に一切言及しません（以下で注記する表現を除く）。摩擦点が仕込まれた小規模な Python ショップバックエンド（浅いバリデータ／金額ヘルパー、リポジトリへ転送するだけの在庫サービス、単一の決済アダプター、カートと注文で重複した割引ロジック、ヘルパーしかカバーしないテスト）に対する 3 つのタスク：report.html として書くコードベース全体のアーキテクチャレビュー、決済と在庫に限定した同じレビュー、チャットで答える「place_order のテストがつらい理由」。スキルあり群のプロンプトは $improve-codebase-architecture で始まり（明示的な呼び出し）、対照群と一文プロンプトは名前を出しません。
3群の比較
| 群 | 平均スコア（0〜5） | 1実行あたりのトークン |
|---|---|---|
| スキルなし | 3.2 | 115k |
| 一文プロンプト | 3.91 | 120k |
| スキルあり | 4.12 | 208k |
Codex CLI で 18 実行を計測し、LLM 判定なしのルールベースのチェックで採点。合計 23.0 / 30、判定は 状況次第。
判定：状況次第（23.0 / 30）。 ソース：mattpocock/skills、skills/engineering/improve-codebase-architecture, skills/engineering/codebase-design、コミット 4ae2317 に固定。インストール：npx skills@latest add mattpocock/skills --skill improve-codebase-architecture。ライセンス： MIT（リポジトリの LICENSE）。
概要
mattpocock/skills の improve-codebase-architecture スキルは、コードベースの「深化の機会」を探します：インターフェースが実装と同じくらい複雑な浅いモジュール、単なるパススルーのレイヤー、仮説上の単一アダプターの継ぎ目、重複したロジック、ヘルパー経由でしかテストされていない振る舞い。候補ごとのビフォー／アフターと最優先の推奨を含む HTML レポートを書きます。語彙については兄弟スキルの codebase-design に依存します。Markdown のみで、スクリプトはありません。
テスト方法
専用の Windows テスト PC 上で Codex CLI 0.166（gpt-6-astra、低推論）、実行ごとに新規の一時プロジェクトと一時 HOME/TMPDIR/キャッシュを使用、スキルをインストール（スキルあり群）、スキルなし（対照群）、またはスキルの中核要件をプロンプト末尾に付けた一文に圧縮（一文プロンプト群）、タスクごとに各群 2 実行、ネットワーク無効、/tmp への書き込みはブロック。プロンプトはスキル名に一切言及しません（以下で注記する表現を除く）。
小さな Python のショップのバックエンドに仕込まれた摩擦（浅いバリデーター／金額ヘルパー、リポジトリへ転送するだけの在庫サービス、単一の決済アダプター、カートと注文で重複した割引ロジック、ヘルパーしかカバーしないテスト）を対象に 3 つのタスクを実施：コードベース全体のアーキテクチャレビュー（report.html として出力）、決済と在庫に限定した同様のレビュー、そしてチャットで答える「place_order のテストが難しい理由」。スキルあり群のプロンプトは $improve-codebase-architecture で始まります（明示的な呼び出し）。対照群と一文プロンプト群はこれに言及しません。
- リポジトリ全体のアーキテクチャスキャン — この小さなショップのバックエンドを、アーキテクチャ改善の観点でレビューしてください：どこを再構成すればコードを変更しやすく、テストしやすくなりますか。調査結果を、このフォルダ内の report.html という自己完結型の HTML レポートとして書いてください（ブラウザを開いたり、サーバーを起動したりしないで…
- 決済と在庫のみ — このバックエンドの決済と在庫の部分だけを見て、どの再構成が効果的か教えてください。調査結果を、このフォルダ内の report.html という自己完結型の HTML レポートとして書いてください（ブラウザを開いたり、サーバーを起動したりしないでください）。コードは変更しないで…
- place_order のテストが難しい理由 — このバックエンドで place_order の適切なテストを書くのは苦痛に感じます。それはなぜですか。どのように再構成すれば解決しますか。ファイルは変更せず、最終メッセージで答えてください。
採点はプログラム的（隠しテスト／仕込み問題の検出／制約チェック／該当する場合はレンダリング+OCR）で、実行ごとに 0〜5 点。スコアはどの LLM 判定者も決めていません。
結果
第 3 の群に与えた一文プロンプト："深化の機会を探してください：インターフェースが実装と同じくらい複雑な浅いモジュール（削除テストを適用：それを削除すると複雑さが集中するのか、それとも移動するだけか）、パススルーのレイヤー、仮説上の単一アダプターの継ぎ目、モジュール間で重複したロジック、実際のインターフェースではなくヘルパー経由でしかテストされていないロジック。各候補を、ファイル、問題、解決策、利点、ビフォー／アフターとともに提示し、最優先の推奨を 1 つ挙げてください。"
| タスク | 対照群スコア | 一文プロンプト | スキルあり | 対照群トークン | 一文プロンプトトークン | スキルありトークン | スキルの読み込み |
|---|---|---|---|---|---|---|---|
| t1-scan | 2.92 | 4.24 | 4.43 | 154k | 158k | 243k | 2/2 |
| t2-focus | 2.08 | 2.5 | 3.75 | 116k | 133k | 228k | 2/2 |
| t3-testing | 4.58 | 5.0 | 4.17 | 74k | 67k | 150k | 2/2 |
平均スコア：スキルなし 3.2 に対しスキルあり 4.12（差 +0.92）。1実行あたりのトークン：115k に対し 208k（1.80 倍）。所要時間 112 秒に対し 135 秒。一文プロンプト群：3.91（一文プロンプトに対するスキルの上乗せ：+0.2、スキルなしに対する一文プロンプトの上乗せ：+0.72）。一文プロンプトのトークンは 1実行あたり 120k で、スキルは一文プロンプトの 1.73 倍のトークンを消費します。
何が起きたか
- 効果が表れるのはコードベース全体のレビューです。スキルありと一文版は、4 実行すべてで 6/6 の仕込みポイントを、アーキテクチャの語彙、ビフォー／アフター、最優先の推奨とともに見つけました。素の Codex は、1 実行で 2/6、もう 1 実行で 6 チェック中 5 を見つけ、どちらの実行にも明確な「最優先の推奨」はありませんでした。
- 対象を絞ったレビュー（決済と在庫のみ）はどの群にも難しいタスクでした。最も良い群でも平均して 2 つの仕込みポイントのうち 1 つを見つけただけです。チェックは対照群 2/4、一文プロンプト 3/4、スキルあり 3/4。スキルは一文より優れていませんでした。
- 「place_order のテストが難しい理由」では、3 群すべてが仕込みの原因（隠された PaymentAdapter、モジュールレベルの共有在庫、重複した割引ロジック、ヘルパーで止まるテスト）を見つけました。スキルありの回答はスキルの語彙（'interface'、'locality'）を使い、対照群も平易な言葉で同様に正しく答えました。
- 平均スコアは対照群 3.20、一文 3.91、スキルあり 4.12。スキルは一文に対して 0.21 上乗せしますが、トークンは 1.7 倍（1実行あたり 208k に対し 120k）です。兄弟スキルも読み込むためです。一文群のコストは対照群（115k）と同じです。
- スキルは 2 つのスキルフォルダをインストールするため、スキルあり群の実行はプロジェクトの .agents フォルダに余分なファイルを作成しました。これらは「コードファイルを変更しない」チェックから除外しています（最初のパスでは誤って不合格になり、チェックの Windows 固有のバグを最終数値の前に修正しました）。
ディメンション別スコア
| ディメンション | スコア | 理由 |
|---|---|---|
| 1_出力品質 | 4.12 | スキルありの平均スコア 4.12/5（プログラム的チェック。タスク別の表を 参照）。 |
| 2_スキルなしに対するリフト | 2.92 | スキルなし 3.20 に対して +0.92 ポイント（タスクごとに n=2。約 1 ポ イント未満の差はノイズ）。 |
| 3_トリガー | 5.0 | スキルあり群 6/6 実行でスキルファイルが読み込まれました。 |
| 4_指示の移植性 | 4 | 兄弟スキル（codebase-design）と、任意で
|
| 5_効率性 | 2 | トークン 1.80 倍（1実行あたり 208k に対し 115k）、時間 1.20 倍（135 秒に対し 112 秒）。 |
| 6_安全性と衛生 | 5 | Markdown のみ。スキャナはクリーン。生成されたレポートの雛形は、ブ ラウザで開くと CDN スクリプトを読み込みます。 |
本テストの限界
- 教科書的な仕込み問題を含む小さな Python フィクスチャ 1 つです。大規模な実リポジトリでレポートが有用かどうかは測定していません。
- レポートの品質、誤検出、HTML のスタイル（ブラウザで開くと Tailwind と Mermaid を CDN から読み込む）は採点していません。スキルが説明するサブエージェントの振る舞いは実行していません。
- 一文プロンプトはスキル自身のチェックリストを言い換えたもので、短いプロンプトの上限と言えます。
- タスク・群ごとに n=2。1 ポイント未満の差はノイズです。
- ルールベースの採点はチェックが検出できるものだけを測ります。センスや、結果が最善かどうかは判定できません。
セキュリティ
security.md を参照。スキャン：CRITICAL 0 / HIGH 0 / MEDIUM 0。判定：実行しても安全（ネットワーク無効のサンドボックス）。クリーンなスキャン結果はスキルの安全性を証明しません。
結論
何もしない場合と比べると、スキルはコードベース全体のレビューを明確に改善します。主にレポートの構造と語彙を強制するためで、トークンは 1.8 倍かかります。同じスメルを列挙した一文でも利益の大半が得られるため、毎回同じレポート形式を求めたい場合にのみインストールする価値があります。
トランスクリプト
実行ログ：improve-codebase-architecture (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.) 列：タスク、群-回、スコア（0-5）、トークン、秒、合格したチェック、エージェントが開いたスキルファイル。 t1-scan control-1: スコア 1.67, トークン 154044, 秒 168.7, チェック 2/6, 開いたファイルなし t1-scan control-2: スコア 4.17, トークン 154957, 秒 158.2, チェック 5/6, 開いたファイルなし t1-scan oneliner-1: スコア 4.24, トークン 158136, 秒 159.2, チェック 6/6, 開いたファイルなし t1-scan oneliner-2: スコア 4.24, トークン 158141, 秒 183.3, チェック 6/6, 開いたファイルなし t1-scan treatment-1: スコア 4.62, トークン 229717, 秒 180.3, チェック 6/6, 開いたファイル codebase-design,improve-codebase-architecture t1-scan treatment-2: スコア 4.24, トークン 258001, 秒 158.7, チェック 6/6, 開いたファイル codebase-design,improve-codebase-architecture t2-focus control-1: スコア 1.25, トークン 107480, 秒 117.6, チェック 2/4, 開いたファイルなし t2-focus control-2: スコア 2.92, トークン 125637, 秒 137.1, チェック 2/4, 開いたファイルなし t2-focus oneliner-1: スコア 2.5, トークン 139088, 秒 200.6, チェック 3/4, 開いたファイルなし
18 実行、3 成果物
サンプル出力
SOTA · With the skill: report.html (t1-scan, run 1, Codex)
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Small shop — architecture review</title> <style> :root{color-scheme:light;--ink:#182b36;--muted:#52616b;--accent:#13745b;--paper:#f5f3ed;--line:#d6ddd8}*{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink);font:16px/1.6 system-ui,sans-serif}main{max-width:1120px;margin:auto;padding:50px 28px}h1,h2,h3{line-height:1.18}h1{font: clamp(34px,5vw,58px)/1.1 Georgia,serif;margin:12px 0}h2{font:30px/1.2 Georgia,serif;margin:12px 0}h3{font-size:16px}a{color:var(--accent)}.eyebrow,.label{font-size:12px;font-weight:750;letter-spacing:.1em;text-transform:uppercase}.muted{color:var(--muted)}header{margin-bottom:30px}.summary,article,.top{background:#fff;border:1px solid var(--line);border-radius:16px;padding:28px;margin:24px 0}article{border-top:4px solid var(--accent)}.badge{display:inline-block;padding:4px 12px;border-radius:20px;background:#dff3e9;color:#07583f;font-size:13px;font-weight:700}.explore{background:#fff0ce;color:#805800}.files{font:13px/1.8 ui-monospace,monospace;color:var(--muted);overflow-wrap:anywhere}.diagrams{display:grid;grid-template-columns:1fr 1fr;gap:20px;margin:24px 0}.diagram{padding:20px;background:#f5f7f5;border-radius:10px}.diagram h3{margin:0 0 18px}.box{border:1px solid #95aaa1;border-radius:6px;background:white;padding:12px;text-align:center}.row{display:flex;gap:10px}.row>*{flex:1}.arrow{text-align:center;color:var(--accent);font-weight:700;padding:6px}.leak{color:#ad3f35}.deep{background:var(--ink);color:#fff;border:4px solid var(--ink);border-radius:8px;padding:16px;text-align:center}.inside{margin-top:12px;border-top:1px solid #7d9b98;padding:12px 4px;color:#d2e4df;font-size:14px}.seam{border-top:2px dashed #80958c;margin:12px 0;padding-top:8px;text-align:center;font-size:13px;color:var(--muted)}p{margin:12px 0}ul{padding-left:22px}li{margin:6px 0}.note{border-left:3px solid #d29b35;padding:8px 14px;background:#fff9eb}.top{background:#e3eee7}.index{display:flex;gap:20px;flex-wrap:wrap}.footer{font-size:13px;color:var(--muted)}@media(max-width:720px){main{padding:24px 14px}.diagrams{grid-template-columns:1fr}article,.summary,.top{padding:20px}}@media print{body{background:#fff}main{padding:0}article{break-inside:avoid}a{color:inherit}} </style> </head> <body><main> <header><div class="eyebrow">Architecture review · 2 November 2026</div><h1>Give shop behavior<br>one place to live.</h1><p class="muted">Three focused opportunities for change locality and test leverage.</p><nav class="index" aria-label="Candidates"><a href="#pricing">01 Pricing</a><a href="#inventory">02 Inventory</a><a href="#order">03 Order execution</a></nav></header> <section class="summary" aria-label="Scope and evidence"> <h2>Scope & confidence</h2> <p>Reviewed all ten Python files in <code>shop/</code>, <code>tests/test_helpers.py</code>, README, and available history at <code>39cbee1</code>. History contains only <code>init</code>; no change hotspots can be inferred. No <code>GLOSSARY.md</code>, <code>docs/adr/</code>, or <code>AGENTS.md</code> was found. Domain names below come from [... excerpt: first 3200 of 13128 characters]