RQ-038: ADR 作成スキル 3 構成パターンのトレードオフ調査レポート

モノリシック型 / 分割型 / OSS ハイブリッド型 — 代表取締役向け実装判断ガイド

注記: 本レポートは adr-kit 単体採用 を最終推奨としている。本リポでは ADR-0019 で adr-kit 採用 + Dify Phase 1 投資撤退 + LangGraph TS 移行 という、より広いパイプライン刷新を実施することを決定した。Decision Pipeline の Triage / Scoring / 本文生成 / 採番までを LangGraph TS + Hono on Cloudflare Workers + LiteLLM Gateway で再構築し、adr-kit は lint / 遺産発掘 / コード ↔ ADR リンクの補完ツールとして導入する。詳細は ADR-0019 を参照。

TL;DR (核心の答え)

トレードオフは構造的には存在するが、Progressive Disclosure (段階的開示) と Subagent 分離という設計パターンで大幅に緩和できる。Anthropic 公式の「SKILL.md = 目次／references/ = 章／scripts/ = 道具」という 3 層モデルは、(a) モノリシック型と (b) 分割型の良いとこ取りを可能にする中間解として機能する。実際 rvdbreemen/adr-kit と skillrecordings/adr-skill はどちらも「外形は 1 スキル、内部は 4–8 ファイルに分散」という同型設計で、業務委託エンジニアからは「ADR は 1 つのコマンド体系」に見える一方、代表取締役側では機能単位のメンテが可能。

来週月曜から始める現実解は「Phase 0: (c) OSS ハイブリッド型をベースに (a) モノリシック型として導入」→「Phase 1: 必要に応じて分割」。具体的には rvdbreemen/adr-kit (MIT, v0.11.0, 2026-04-25 最終更新) を /plugin install で入れ、docs/adr/ 配置・四要素 + Notes for Successor・遡及 ADR 用の /adr-kit:migrate までそのまま流用し、SKILL.md は英語のまま、ADR 本体テンプレと references/bizlink-domain.md (GAS / clasp / LiteLLM マスキング / 会計ドメイン) だけ自前で日本語化する構成が、初期セットアップ数時間で動き、業務委託への引き継ぎコストが最小。

「自分しか開発できない仕組み」を避ける観点では、純粋な (b) 分割型 (5 本前後) は現時点で 非推奨。複数スキル間の依存・起動判断・version skew・marketplace update の silent failure (Anthropic 公式 issue #46594 / #47237 で報告済み) が業務委託エンジニアの認知負荷を直撃する。一方、(a) モノリシック型を「500 行・5,000 トークン」のしきい値で運用しつつ Phase 2 で必要部分だけ分割する段階進化型が、代表取締役の BizDev 移行スケジュールと整合する。

Key Findings (重要な発見)

1. Anthropic 公式の設計思想は「内部分割つきの外形モノリシック」

• 500 行 / 5,000 トークンの硬い線: 公式 Skill authoring best practices は「SKILL.md body は最適性能のため 500 行以下に保ち、超えたら references/ に分離」と明示。Anthropic 自身の 17 公式スキルの本文中央値は約 2,000 トークン、最大は skill-creator の約 8,000 トークン (newsletter.swirlai.com 計測値)。
• Progressive Disclosure の 3 層: frontmatter (常時ロード, ~80–100 トークン/スキル) / SKILL.md 本文 (マッチ時ロード) / references/ scripts/ assets/ (必要時ロード, scripts はコード自体は文脈に乗らない)。「外から見ると 1 スキル、内側ではファイル単位で薄い」設計が公式が推す中間形態。
• description が決定的: Anthropic skill-creator は記述最適化のために 20 本の fake prompt (10 本 trigger / 10 本 no-trigger) を作り、60% train / 40% held-out で評価し、各クエリ 3 回実行で trigger 率を測定、最大 5 イテレーションで改善する仕組みを内蔵。Anthropic 自身がこれを 6 つの公式 document スキルに適用して 5/6 で改善を確認したと報告。

2. 命令容量の上限は「150–200 命令で遵守率が一様に低下」が定量化されている

• arXiv 論文 On the Paradoxical Interference between Instruction-Following and Task Solving は、Claude Sonnet 4.5 でも測定可能な性能劣化を確認、30–70B 級モデルは制約下で元性能の 65–85% しか保持しないと報告。
• 実務的な観察値として、buildtolaunch.substack.com の Jenny の audit (192 ファイル) と dev.to の Mikedolan の体験談はいずれも「300 行で具体ルールが原則に埋もれ始め、500 行で精度が顕著に劣化、200 本ルールを書けば Claude Code がほぼ無視する」と報告。これが Anthropic 公式の 500 行ガイドラインの実証根拠。
• 重要な含意: (a) モノリシック型の SKILL.md に「作成・更新・索引化・遡及発掘・lint・superseded 連鎖」を全部書こうとすると 500 行は確実に超え、命令容量の崖から落ちる。Progressive Disclosure を使えば本文は 200–300 行に保ったまま機能を入れられる。

3. OSS 実装 3 つのコード構造比較 (2026 年 5 月時点)

adr-kit の構造詳細:

• /adr-kit:setup がプロジェクトの CLAUDE.md に「ADR Kit Rules」セクションを冪等的に追記。
• /adr-kit:lint は 4 ゲートに対する file:line citations 付きで pass/fail を返す。
• /adr-kit:migrate は legacy ADR を canonical-seven-section テンプレートに「read-then-confirm」で書き換える (代表取締役の Phase 0 遡及 ADR 作成と完全一致)。

4. Open8/Zenn の ADR Creator skill (日本語事例)

zenn.dev/open8/articles/6ea54dae208c6f は日本語コミュニティの代表的な実装事例で、完全な (a) モノリシック型:

• 1 つの skill .claude/skills/adr-creator/ をリポジトリ内に配置 (メンバー全員が使える)
• Nygard 原典 4 要素 (Title / Context / Decision / Consequences) + 独自で「決めていないこと」セクションを追加
• スキル化の効果として「フォーマット統一」「暗黙知の形式知化」「ADR 経験少ないメンバーでも品質高い記録を残せる」を報告
• 周辺装置として docs/adr/ への merge 検知の GitHub Actions → Slack 通知、定例アジェンダへの組み込みで「組織に届ける」仕組みも併設

これは代表取締役が想定する規模 (ソロ → 業務委託 1–2 名) と最も近いベンチマーク。「単一スキル全部入りでも実用性十分」 が実証されている。

5. 「分割型」の代表事例 — 大規模だが代表取締役の規模では過剰

terrylica/cc-skills (23 plugins, 11 bundled skills in itp alone) や affaan-m/everything-claude-code、VoltAgent/awesome-agent-skills (1000+ skills) は、いずれも大規模チーム / OSS コミュニティ向けの構成。注目すべきは affaan-m/everything-claude-code 内の architecture-decision-records スキルが 1 スキル単体で実装されている点。「大規模 marketplace を作っているチームほど、ADR は 1 スキルにまとめる」傾向は分割型の限界を示している。

6. 失敗パターンの実証

• モノリシック肥大化: buildtolaunch.substack.com の audit (192 ファイル) は「重複 skill、命名衝突、矛盾ルール」が 500 行超で頻発と報告。mindstudio.ai は「3 つの間違い: skill overload, default configurations, monolithic files」を体系化し、いずれも root cause は「more is automatically better」という誤った前提と分析。
• OSS 塩漬けリスク: Anthropic 公式 issue #46594 は /plugin marketplace update がインストール済プラグインを silent fail で更新しない問題を報告 (2026-04, 未解決)。issue #47237 は VS Code 拡張で 2 つ目の marketplace 追加後に「No plugins available」になるバグ (anthropic-agent-skills の 14MB ペイロードが OS pipe buffer を超過)。OSS 依存型でも Anthropic 自身の marketplace 基盤がまだ不安定。
• 分割型の依存複雑化: alexop.dev と medium.com/SandeepTnvs はいずれも「skills は recipe、subagents は specialist」という分業を推奨するが、サブエージェント間のステート共有が context: fork で隔離されるため、ADR のような「番号採番 → 重複チェック → supersede 連鎖更新 → indexer 同期」という強い順序依存タスクでは、分割した瞬間にオーケストレーション問題に変わる。

7. 業務委託エンジニア (日本市場 2026 年) の習熟度

• claudecode.co.jp の市場観測: 月単価 70–90 万円帯のエンジニアに対する Claude Code 専門求人が 2026-03 以降増加。Offers.jp に Claude Code 業務委託案件多数 (年収 1,000–1,200 万円水準も)。インターネット・アカデミーが 2026-04-30 に「Claude Code 研修」(全 6 回 12 時間) をリリース。
• ただし「ADR を知っているが Claude Code Skills は初めて」が大多数の想定が現実的。zenn.dev/narun の「スキルを作るスキル」記事は「公式の skill-creator を使えば作り方を知らなくてもよい」と結論しており、業務委託エンジニアには 「Claude Code の中で完結する操作」 が認知負荷的に最適。
• 複雑な分割型は引き継ぎコストが跳ねる: 開発者ブログ複数で「3–4 スキル並列以上で生産性増加よりメンタルオーバーヘッドが先に増える」と報告 (zenn.dev/studypocket の「ハッカソン優勝者ガイド」翻訳版より)。

8. CLAUDE.md 英語化の根拠 (代表取締役の方針の追認)

• m-totsu.com と qiita.com の記事は、Claude の認識精度が英語約 96% / 日本語約 92%、トークン効率は英語が 15–20% 優位、と一貫して報告。
• 公式 Multilingual Support の Opus 4.1 ベンチでは日本語性能 96.9% で「ほぼ同等」だが、CLAUDE.md / SKILL.md は毎セッション読まれるためトークン効率の差が積算される。
• 代表取締役の「設定系英語、ADR 本体日本語」のハイブリッド方針はコミュニティ実証ベストプラクティスに完全合致。

9. GAS + clasp スタックとの統合は 2026-04 以降ネイティブ化済み

• google/CLASP リポジトリは 2026 年に /plugin install @google/clasp で Claude Code プラグインとして直接導入可能に。MCP サーバとしても起動できる。
• jlhernando.com の実例は GAS 1,500 行プロジェクトを Claude Code + clasp で運用し、catchUpMissingWeeks() の追加のようなアーキテクチャ変更を実装する流れを示している。ここで ADR を併用すれば、appsscript.json のスコープ変更や clasp deploy のバージョニング判断が再利用可能な意思決定として残る。

Details (実装に必要な詳細)

A. 3 案の徹底比較表 (代表取締役の状況での実測ベース)

B. Progressive Disclosure による「中間設計」の具体例

代表取締役が (a) を選ぶ場合の推奨ディレクトリ構造 (adr-kit の構造を参照しつつ自前構築する場合):

.claude/skills/bizlink-adr/
├── SKILL.md                              # 200–300 行: トリガー、四要素、Notes for Successor、命名規則
├── references/
│   ├── nygard-template.md                # 4 要素テンプレ (日本語)
│   ├── successor-notes.md                # 「Notes for Successor」の書き方ガイド (業務委託向け)
│   ├── superseded-chain.md               # supersede 連鎖の管理ルール
│   ├── retroactive-mining.md             # Phase 0 用: 既存コード/コミットから ADR 候補を発掘する手順
│   ├── lint-checklist.md                 # 4 ゲート相当 (Completeness, Evidence, Clarity, Consistency)
│   └── bizlink-domain.md                 # GAS, clasp, appsscript.json, LiteLLM マスキング, 会計ドメイン固有の罠
├── assets/
│   ├── ADR-template.md                   # 日本語テンプレ
│   └── README-index-template.md
└── scripts/
    ├── new-adr.sh                        # 番号採番 + 雛形生成
    ├── lint-adr.py                       # オフラインで走る lint
    └── update-index.py                   # docs/adr/README.md の自動更新

この設計は外形上モノリシックで業務委託には「bizlink-adr という 1 スキル」に見えるが、代表取締役側では references/ ファイルを単独編集できる。Anthropic 公式 PDF 処理スキルがまさにこの構造 (pdf/ + FORMS.md + reference.md + scripts/) を採用しており、newsletter.swirlai.com の計測でも一般的なパターンとして確立している。

dev.to の Phil Whittaker の論考は 「Monolithic skills should be the starting form. ... You graduate to index-plus-references when the monolith exceeds Anthropic's published guideline of roughly five hundred lines or five thousand tokens」 と明示しており、Phase 0 でモノリシック → 容量が逼迫した時点で分割、という段階進化が Anthropic コミュニティの標準推奨。

C. (c) OSS ハイブリッド型の最短構築手順 (来週月曜から)

# Step 1: adr-kit を導入 (10 分)
/plugin marketplace add rvdbreemen/adr-kit
/plugin install adr-kit@rvdbreemen-adr-kit
/reload-plugins
/adr-kit:setup
# CLAUDE.md に "ADR Kit Rules" セクション追記 (冪等)

# Step 2: 既存 ADR があれば lint で診断 (即座)
/adr-kit:lint           # 4 ゲート (Completeness, Evidence, Clarity, Consistency) で pass/fail

# Step 3: BizLink 固有の references/ を上書き (30 分–1 時間)
# .claude/skills/adr-kit/references/bizlink-domain.md を作成し、以下を記述:
# - GAS 固有罠 (clasp deploy のバージョニング、appsscript.json の oauth scope 変更)
# - LiteLLM マスキング層との整合性 (機密情報の ADR 本文での扱い: マスク後の値だけ記録)
# - 会計ドメイン固有の用語 (CFO/CEO ダッシュボード, KPI カテゴリ)
# - Notes for Successor の追記指示

# Step 4: テンプレートに「Notes for Successor」セクションを追加 (10 分)
# adr-kit の examples/ADR-template.md を copy → 編集 → references/ から参照

# Step 5: Phase 0 — 遡及 ADR 10–15 本作成 (数日)
/adr-kit:migrate        # legacy-shaped MD を canonical-seven-section に変換、TODO placeholder

総初期コスト: 2–4 時間 (Phase 0 の遡及 ADR 本文執筆は別途数日)。

D. 業務委託エンジニアへの引き継ぎコスト見積り

Caveats (注意点と未確定要素)

1. adr-kit の stargazer 数は 2026-05 時点で 0、pre-1.0: toolkit は機能するが API/conventions が v1.0.0 までに変わる可能性あり。README の指示通り「特定タグへの pin」を本番運用では推奨。OSS メンテナ (Robert van den Breemen) は OTGW-firmware で別プロジェクトを活発に維持しているが、adr-kit へのコミット頻度はやや低め。メンテ停止リスクが顕在化したら、.claude/skills/adr-kit/ をリポジトリにコピーして固定すれば塩漬け対策可能 (MIT ライセンスのため自由)。

2. /plugin marketplace update の silent failure (issue #46594) は 2026-05 時点で未解決: プラグイン更新が成功表示でも実際には適用されないバグがある。/reload-plugins 後にスキルが見えなければ /plugin install を再実行する運用が安全。

3. Anthropic skill versioning の正式仕様は 2026-05 時点で「marketplace.json 内の version フィールド」レベル: semver は plugin authors の自主運用。重要な ADR スキルは git タグで pin し、claude plugin tag コマンド (2026-04 導入) で version 管理を併用するのが現実解。

4. 「200 プロンプトテストで起動率 20% → 90%」という具体的数値は Anthropic の公開数値ではない: skill-creator の公式ドキュメントは「6 つの内蔵 document スキル中 5 つで improvement 確認」という質的記述に留まる。20 本の trigger / no-trigger プロンプト × 3 回実行 × 5 イテレーションという評価フレームワーク自体は公式だが、代表取締役のドメインで同じ起動率改善が出るかは個別に skill-creator の eval ループを回して確認する必要がある。

5. Open8 の ADR Creator skill の公開時期は 2026 年 (Zenn 記事ベース): 本文の記事公開時点で「.claude/skills/ に配置」とあり、代表取締役の検討タイミング (2026-05) と整合する一次情報。ただし社内リポジトリの内容そのものは非公開。

6. archgate と log4brains は ADR-as-rules / static-site という別レイヤー: 代表取締役の目的 (ADR 作成・遡及・lint・supersede 連鎖) に直接対応するのは adr-kit。archgate は executable rules 機能が魅力だが、TypeScript で書かれた companion .rules.ts が必要なため、GAS 主体の代表取締役スタックでは導入コストが見合わない。log4brains は静的サイト生成が目的のためスコープがずれる。

7. 「日本語ネイティブの業務委託エンジニアが Claude Code Skills に対する習熟度」の体系的調査は不在: 記事ベースでは「研修サービスが 2026-04 以降立ち上がっている = 市場でまだ普及途上」が確認できるのみ。「初日に迷わない」を担保するには、構成にかかわらず (1) /adr-kit:setup のような 1 コマンドでセットアップ完了する仕組み、(2) CLAUDE.md 内に簡潔な使い方セクション、(3) 1 本のサンプル ADR が必要、という現場知見は普遍的。

8. Phase 0 → Phase 2 の構成変更は (c) → (a)/(b) の方向が容易、逆は困難: OSS ベースで始めて足りなくなった部分を自前 references/ 追加 → 自前スキル化、という流れは既存ファイルが grow するだけで済む。逆に自前 (a) で 3–4 ヶ月運用してから (c) に移行すると、独自テンプレ・命名規則を adr-kit のフォーマットに合わせる手戻りが発生する。「来週月曜から (c) で始める」が後悔最小の選択。

9. 本レポートは AI 生成情報を含む二次情報源 (Substack, Medium, Zenn 個人記事) の比重が高い: Anthropic 公式ドキュメント・GitHub 一次情報・arXiv 論文を骨格としつつ、コミュニティの実証は推測と事実が混在しているため、特に「500 行で精度劣化」「英語 96% vs 日本語 92%」などの数値は order-of-magnitude として読み、代表取締役自身の環境で skill-creator の eval ループで再確認する余地を残すこと。

最終推奨

来週月曜の最初の 1 時間で:

/plugin marketplace add rvdbreemen/adr-kit
/plugin install adr-kit@rvdbreemen-adr-kit
/reload-plugins
/adr-kit:setup

を実行し、Phase 0 の遡及 ADR 作成は /adr-kit:migrate を使う。references/bizlink-domain.md だけ自前で日本語で書き、SKILL.md 本体 (英語) は触らない。3–6 ヶ月後に BizDev 移行する時点で、もし adr-kit のメンテが滞っていれば .claude/skills/ 配下にコピーして固定する。

これが「業務委託エンジニアの認知負荷最小」「代表取締役のメンテ負荷最小」「OSS 停止リスクへの脱出口確保」の 3 点を同時に満たす唯一の解。

本リポでの採用方針 (RQ-038 → ADR-0019 への展開)

本レポートは adr-kit 単体採用 + 自前モノリシック型 → OSS ハイブリッド の段階進化を最終推奨とするが、本リポでは以下の理由で adr-kit 採用 + Decision Pipeline 全面刷新 (Dify 退役 + LangGraph TS 移行) に発展させた:

1. Decision Pipeline (Dify Phase 1 検証済 / Phase 2a 未着手) との機能重複が判明
2. Dify は完全 CI/CD 化が事実上不可能 (DSL import API が 2026-05 現在も非公式 — Issue #24087 / #27795 open)
3. 「手動操作をできるだけなくしたい」という代表取締役の強い要件

Phase 2a 未着手のため並行稼働期間は不要、Phase 1 投資 (Triage v0.2 / Scoring v0.1 プロンプト) は LangGraph node に手作業移植 (半日〜1 日)。adr-kit は補完ツールとして導入し、lint / 遺産発掘 / コード ↔ ADR リンクチェックを担当。詳細は ADR-0019 を参照。

参照

• ADR-0019: Decision Pipeline LangGraph 移行 + adr-kit 採用 + Dify 退役
• ADR-0007: Gemini Receipt Parsing
• ADR-0008: Vertex AI 集約
• ADR-0010: モジュラーモノリストと 3 桁番号体系
• RQ-033: 採用戦略
• RQ-037: 創立費の会計処理

主要参考リンク (Gemini Deep Research の引用元抜粋)

• Anthropic Skill Authoring Best Practices (公式)
• arXiv: On the Paradoxical Interference between Instruction-Following and Task Solving
• rvdbreemen/adr-kit (GitHub, MIT, v0.11.0)
• skillrecordings/adr-skill (GitHub)
• archgate (公式サイト, Apache-2.0)
• Anthropic GitHub Issues #46594, #47237 (marketplace update silent failure)
• Open8 ADR Creator (zenn.dev/open8/articles/6ea54dae208c6f)
• affaan-m/everything-claude-code / terrylica/cc-skills / VoltAgent/awesome-agent-skills
• claudecode.co.jp / Offers.jp (業務委託市場観測)
• インターネット・アカデミー Claude Code 研修 (2026-04-30 リリース)
• google/CLASP Claude Code プラグイン化 (2026-04)
• jlhernando.com (GAS + Claude Code 実例)