codebase-design (mattpocock/skills)
小さなインターフェースと明確な継ぎ目を持つ「深いモジュール」を設計するための共通語彙を提供します。
codebase-design：アーキテクチャレビューに深掘りの語彙と、より明確な構造をもたらします（対照群 3.2、スキルあり 3.9、一文プロンプト 4.5）。トークンは 1.1 倍ですが、仕込まれた問題点を一文プロンプトより多く見つけることはありませんでした。
Codex CLI · gpt-6-astra
23.6 / 30
スキルなしに対するリフト：+0.71 · 状況次第 · 18 実行
状況次第：リフト +0.71 が +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.7
- 出力品質
- 3.9
- トークンと時間のコスト
- 4.0
- インストールと移植性
- 4.0
- 安全性
- 4.0
セキュリティレビュー
安全静的スキャン：CRITICAL 0 / HIGH 0 / MEDIUM 0。手動レビュー：ネットワーク無効のサンドボックスで実行しても安全（指摘なし）。クリーンなスキャン結果はスキルの安全性を証明しません。
インストール
npx skills@latest add mattpocock/skills --skill codebase-design
固定コミット: 4ae2317ddb22b046e26455e4f9c9b3aaaf62212d
テスト済み: 2026-11-02
テスト内容
- リポジトリ全体のアーキテクチャスキャン — この小さなショップのバックエンドをアーキテクチャ改善の観点でレビューしてください：どこを再構築すればコードを変更しやすく、テストしやすくなるでしょうか。結果をこのフォルダーの report.html という自己完結の HTML レポートに書いてください（ブラウザを開いたりサーバーを起動したりしな…
- 支払いと在庫のみ — このバックエンドの支払いと在庫の部分だけを見て、どの再構築が効果的かを教えてください。結果をこのフォルダーの report.html という自己完結の HTML レポートに書いてください（ブラウザを開いたりサーバーを起動したりしないでください）。また、コードは一切変更しな…
- place_order のテストが難しい理由 — このバックエンドで place_order の適切なテストを書くのは苦痛に感じます。それはなぜで、どのような再構築で解消できるでしょうか。ファイルは変更せず、最終メッセージで回答してください。
長所
- スキルなしと比べ平均スコアを 3.21 から 3.92 に引き上げ（+0.71）。
- スキルは名前を出さずとも採用されました：スキルあり群 6/6 実行でスキルファイルが読み込まれました。
短所
- 一文プロンプトは 4.54、スキルありは 3.92（-0.63）。
- タスク・群ごとに n=2。1 ポイント未満の差はノイズです。
レビュー
専用の Windows テスト PC 上で Codex CLI 0.166（gpt-6-astra、低推論）、実行ごとに新規の一時プロジェクトと一時 HOME/TMPDIR/キャッシュを使用、スキルをインストール（スキルあり群）、スキルなし（対照群）、またはスキルの中核要件をプロンプト末尾に付けた一文に圧縮（一文プロンプト群）、タスクごとに各群 2 実行、ネットワーク無効、/tmp への書き込みはブロック。プロンプトはスキル名に一切言及しません（以下で注記する表現を除く）。仕込まれた摩擦ポイントが 6 つある小さなショップのバックエンド（浅いバリデーターと金額ラッパー、素通しの在庫サービス、単一の支払いアダプター、重複したロジックなど）。タスク：アーキテクチャ改善の HTML レポートを書く、支払いと在庫に限定したレポート、そして「place_order のテストが難しい理由とその修正方法」（チャットで回答）。プロンプトは設計用語を一切名指ししません。一文プロンプト群は深掘りの考え方と、指摘すべき事項を一文で述べます。
3群の比較
| 群 | 平均スコア（0〜5） | 1実行あたりのトークン |
|---|---|---|
| スキルなし | 3.21 | 119k |
| 一文プロンプト | 4.54 | 114k |
| スキルあり | 3.92 | 133k |
Codex CLI で 18 実行を計測し、LLM 判定なしのルールベースのチェックで採点。合計 23.6 / 30、判定は 状況次第。
判定：状況次第（23.6 / 30）。 出典：mattpocock/skills、skills/engineering/codebase-design、コミット 4ae2317 に固定。インストール：npx skills@latest add mattpocock/skills --skill codebase-design。ライセンス： MIT（リポジトリの LICENSE）。
概要
mattpocock/skills の codebase-design スキル：モジュールの深さでアーキテクチャをレビューする手法。深いモジュールは、小さなインターフェースで多くの振る舞いを隠します。浅いパススルーモジュール、仮説にすぎない単一アダプターの継ぎ目、重複したロジック、ヘルパー経由でしかテストされない振る舞いを指摘し、継ぎ目をどこに置くべきかを示して、振る舞いがインターフェースを通してテストされるようにします。
テスト方法
専用の Windows テスト PC 上で Codex CLI 0.166（gpt-6-astra、低推論）、実行ごとに新規の一時プロジェクトと一時 HOME/TMPDIR/キャッシュを使用、スキルをインストール（スキルあり群）、スキルなし（対照群）、またはスキルの中核要件をプロンプト末尾に付けた一文に圧縮（一文プロンプト群）、タスクごとに各群 2 実行、ネットワーク無効、/tmp への書き込みはブロック。プロンプトはスキル名に一切言及しません（以下で注記する表現を除く）。
6 つの摩擦ポイント（浅いバリデーターと金額ラッパー、パススルーの在庫サービス、単一の決済アダプター、重複ロジックなど）を仕込んだ小さなショップのバックエンド。タスク：アーキテクチャ改善点を HTML レポートにまとめる、決済と在庫に限定したレポートを作る、「place_order がテストしにくい理由と修正方法」をチャットで回答。プロンプトは設計用語を一切含みません。一文プロンプトは「深さ」の考え方と指摘すべき項目を述べます。
- リポジトリ全体のアーキテクチャスキャン — この小さなショップのバックエンドを、アーキテクチャ改善の観点でレビュー：どこを再構成すればコードを変更しやすく、テストしやすくなるか？調査結果を、このフォルダに report.html という自己完結した HTML レポートとして書いてください（ブラウザを開いたり、サーバーを起動したり…
- 決済と在庫のみ — このバックエンドの決済と在庫の部分だけを見て、どの再構成が効果的かを教えてください。調査結果を、このフォルダに report.html という自己完結した HTML レポートとして書いてください（ブラウザを開いたり、サーバーを起動したりせず）、コードは一切変更せず…
- place_order がテストしにくい理由は？ — このバックエンドの place_order について、きちんとしたテストを書くのがつらく感じます。なぜか、またどんな再構成で解消できるか？ファイルは変更せず、最終メッセージで回答してください。
採点はプログラム的（隠しテスト／仕込み問題の検出／制約チェック／該当する場合はレンダリング+OCR）で、実行ごとに 0〜5 点。スコアはどの LLM 判定者も決めていません。
結果
第 3 群に与えた一文プロンプト："モジュールを深さで評価する：深いモジュールは小さなインターフェースで多くの振る舞いを隠す。浅いパススルーモジュール、仮説上の単一アダプターの継ぎ目、重複したロジック、ヘルパー経由でしかテストされない振る舞いを指摘し、継ぎ目をどこに置くべきかを述べて、振る舞いがインターフェースを通してテストされるようにする。"
| タスク | 対照群スコア | 一文プロンプト | スキルあり | 対照群トークン | 一文プロンプトトークン | スキルありトークン | スキル読み込み |
|---|---|---|---|---|---|---|---|
| t1-scan | 2.54 | 3.63 | 3.83 | 135k | 135k | 177k | 2/2 |
| t2-focus | 2.5 | 5.0 | 3.75 | 153k | 139k | 148k | 2/2 |
| t3-testing | 4.58 | 5.0 | 4.17 | 65k | 65k | 72k | 2/2 |
平均スコア：スキルなし 3.21 vs スキルあり 3.92（差分 +0.71）。1 実行あたりのトークン：119k vs 133k（1.12 倍）。時間：154s vs 158s。一文プロンプト群：4.54（一文プロンプトに対するスキルの上乗せ：-0.63。一文プロンプト自身のスキルなしに対する上乗せ：+1.34）。一文プロンプトのトークンは 1 実行あたり 114k、つまりスキルのコストは一文プロンプトの 1.17 倍。
何が起きたか
- 対照群 3.21、スキルあり 3.92、一文プロンプト 4.54（各 n=6）。ガイダンスなしでは、HTML レポートは 4 実行すべてでアーキテクチャ用語をほぼ使いませんでした（deep/shallow/seam/interface の使用が 0〜2 回。チェックは 6 回を要求）。スキルありのレポートは 4 実行すべてで用語を使い、一文プロンプトも同様でした。
- バックエンド全体のスキャン：スキルあり 4.24 と 3.41、一文プロンプト 3.41 と 3.86、対照群 2.88 と 2.2。ガイド付きの両群は 6 つの仕込みポイントのうち 3〜4 を検出。浅いバリデーターのラッパーと単一決済アダプターは、どの群も複数の実行で見落としました。
- 決済と在庫に絞ったタスク：スキルありは両方の実行で 3.75、対照群は両方で 2.5、一文プロンプトは両方で 5.0。スキルありと対照群の全実行は 2 つのポイントのうち 1 つしか検出できず（仮説上の単一決済アダプターを見落とし）、一文プロンプトは両方を見つけました。
- place_order がテストしにくい理由：すべての群が拮抗（対照群 4.17 と 5.0、スキルあり 4.17 と 4.17、一文プロンプト 5.0 と 5.0）。スキルありの実行は、一方で 1 つの原因（ヘルパー経由のみのテスト）を、もう一方でパススルー層を見落としました。
- トークン：1 実行あたりスキルあり 133k、一文プロンプト 114k、対照群 119k（対照群の 1.12 倍）。スキルはスキルあり群 6/6 実行で読み込まれました。
評価項目別スコア
| 評価項目 | スコア | 理由 |
|---|---|---|
| 出力品質 | 3.92 | スキルありの平均スコアは 3.92/5（プログラム的チェック。タスク別の表を参照）。 |
| スキルなしに対するリフト | 2.71 | スキルなしの 3.21 に対して +0.71 ポイント（タスクごとに n=2。約 1 ポイント未満の差はノイズ）。 |
| トリガー | 5.0 | スキルあり群 6/6 実行でスキルファイルが読み込まれました。 |
| 手順の移植性 | 4 | SKILL.md と少数の参照ファイル。 |
| 効率 | 4 | トークン 1.12 倍（1 実行あたり 133k vs 119k）、時間 1.03 倍（158s vs 154s）。 |
| 安全性と衛生 | 4 | 文章のみ。security.md を参照。 |
このテストの限界
- レポート本文（ファイル名付近のキーワード）に対するルールベースの再現チェックと語彙カウント。提案された再構成が妥当かは判定しておらず、レポートをブラウザで開いてもいません。
- 語彙チェックはスキル自身の用語を有利に扱い、一文プロンプトも同じ用語を挙げるため、ガイド付きの群に有利です。
- 「before/after」チェックは、スキャンのタスクだけで失敗した 2 実行にのみ現れます。差別化要因ではありません。
- セルごとに n=2。小さなコードベース 1 つ。
- タスク・群ごとに n=2。約 1 ポイント未満の差はノイズです。
- ルールベースの採点はチェックが捉えられる範囲を測るもので、センスや、その結果が最善かどうかは判定できません。
セキュリティ
security.md を参照。スキャン：CRITICAL 0 / HIGH 0 / MEDIUM 0。判定：実行しても安全（ネットワーク無効のサンドボックス）。クリーンなスキャン結果はスキルの安全性を証明しません。
結論
このスキルは、素のプロンプトにはない「モジュールの深さ」という枠組みをレビューに明確に与え、対照群に対してわずかなスコア向上をもたらします。ただし同じ考え方を一文にすると、より少ないトークンでより多くの仕込み問題を検出するため、その効果は主に表現上のものです。
トランスクリプト
実行ログ：codebase-design (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.) 列：タスク、群-回、スコア（0-5）、トークン、秒、合格したチェック、エージェントが開いたスキルファイル。 t1-scan control-1: スコア 2.88, トークン 135577, 秒 182.2, チェック 4/6, 開いたファイルなし t1-scan control-2: スコア 2.2, トークン 136096, 秒 168.8, チェック 4/6, 開いたファイルなし t1-scan oneliner-1: スコア 3.86, トークン 135437, 秒 152.3, チェック 5/6, 開いたファイルなし t1-scan oneliner-2: スコア 3.41, トークン 135611, 秒 172.2, チェック 4/6, 開いたファイルなし t1-scan treatment-1: スコア 3.41, トークン 176681, 秒 216.0, チェック 4/6, 開いたファイル codebase-design t1-scan treatment-2: スコア 4.24, トークン 178425, 秒 181.7, チェック 6/6, 開いたファイル codebase-design t2-focus control-1: スコア 2.5, トークン 164638, 秒 128.2, チェック 2/4, 開いたファイルなし t2-focus control-2: スコア 2.5, トークン 143158, 秒 298.9, チェック 2/4, 開いたファイルなし t2-focus oneliner-1: スコア 5.0, トークン 112021, 秒 375.7, チェック 4/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 backend — architecture review</title> <style> :root{color-scheme:light;--ink:#183047;--muted:#506276;--accent:#116b66;--line:#d8e2e8}*{box-sizing:border-box}body{margin:0;background:#f3f6f8;color:var(--ink);font:16px/1.65 system-ui,sans-serif}main{max-width:1060px;margin:auto;padding:48px 28px 70px}header{border-top:6px solid var(--accent);padding:24px 0}h1{font-size:2.5rem;line-height:1.15;letter-spacing:-.04em}h2{font-size:1.55rem;margin-top:0}h3{font-size:1.1rem;margin-bottom:6px}p{margin:10px 0 18px}.eyebrow,.meta{color:var(--muted)}.eyebrow{text-transform:uppercase;letter-spacing:.13em;font-size:.8rem;font-weight:700}section{background:white;border:1px solid var(--line);border-radius:12px;padding:26px;margin:22px 0}code,pre{font-family:Consolas,monospace;font-size:.9em}code{overflow-wrap:anywhere}pre{background:#edf4f5;padding:18px;white-space:pre-wrap;border-left:4px solid var(--accent)}table{width:100%;border-collapse:collapse;font-size:.93rem}th,td{text-align:left;vertical-align:top;padding:12px;border-bottom:1px solid var(--line)}th{background:#edf4f5}a{color:var(--accent)}.tag{display:inline-block;background:#e3f2ef;color:#155b53;border-radius:20px;padding:3px 10px;font-size:.8rem;font-weight:700}.note{border-left:4px solid #d1a03b;padding-left:16px}.flow{display:flex;gap:12px;flex-wrap:wrap;margin:18px 0}.flow div{flex:1;min-width:180px;background:#edf4f5;padding:16px;border-radius:8px}li{margin:8px 0}@media(max-width:650px){main{padding:24px 14px}section{padding:18px}h1{font-size:2rem}table{font-size:.83rem}th,td{padding:7px}}@media print{body{background:white}main{padding:0}section{break-inside:avoid}a{color:inherit}} </style> </head> <body><main> <header><div class="eyebrow">Architecture review · 2 November 2026</div> <h1>Make pricing and ordering the test surface.</h1> <p>The highest-value restructuring is to concentrate pricing policy in one pure module and let an order module own validation, stock decisions, and payment sequencing behind a small interface. Remove pass-through layers as this happens. This backend is small enough that a framework, generic repository hierarchy, or distributed decomposition would add more work than leverage.</p> <p class="meta">Scope: all ten Python files in <code>shop/</code>, <code>tests/test_helpers.py</code>, and the README. This report proposes changes; no application or test files were edited. Source references use the line numbers of the reviewed snapshot.</p> <nav aria-label="Report contents"><a href="#pricing">Pricing</a> · <a href="#orders">Order module</a> · <a href="#stock">Stock consistency</a> · <a href="#validation">Validation</a> · <a href="#plan">Migration & tests</a></nav> </header> <section><h2>Current structure and where knowledge leaks</h2> <pre aria-label="Current dependency diagram">cart ──→ money pricing (discount implementation) └── own discount rules ↑ imported by orders, never called orders ──→ validators + money + own discount rules ├─→ inventory_service ──→ inventory_repo ──→ g [... excerpt: first 3200 of 17083 characters]