# エージェント型の委譲が全滅したら「API 直叩きのファイル単位生成＋許可リスト書き出し」で実装を通す ## この指示書が解く問題 監督役の AI（Claude Code など）が実装を外部のコーディングエージェント（Codex / gemini-cli / 安価モデルの agentic ランナー）へ委譲する構成で、**委譲先が全部落ちる**ことがある。 - Codex の WSL 経路が無い（Windows 版 Codex は read-only で書けない既知バグ） - gemini-cli が `402 prepayment credits are depleted`（前払いクレジット枯渇） - 安価モデルの agentic ランナーが、親と同じ hook 設定を継承して「実装コードを書くな」と自分でブロックされる このとき監督が自分で全部書くとコストが跳ねる。**素の Chat Completions API を 1 回叩いてファイル全文を出させ、許可リストに載ったパスだけ書き出す**と、agentic ランナーの hook・サンドボックス・classifier をいっさい通らずに実装を通せる。18 ファイル・約 1,500 行を 4 並列で生成し、監督の手直しは型エラー 1 行＋レビュー指摘 2 点だけだった実績がある（DeepSeek、出力 16k tok、約 $0.02）。 ## 手順（AI に読ませればそのまま動く） ### 1. 指示書をファイルで書く（argv に載せない） - 変更するファイルを **パスごとに列挙**し、新規は関数シグネチャ、変更は「既存内容を全て保持したうえで何を足すか」を書く。 - テストケースも「ケース 1〜7」の粒度で列挙する。 - 冒頭に「あなたは実装者。再委譲禁止。列挙したファイル以外は触らない。git / パッケージマネージャ / テスト実行はしない（監督が実行する）」を入れる。 - Windows はコマンドライン長が 32k 文字なので、指示書＋既存ソース（3 万字超）は **必ずファイル経由**で渡す。 ### 2. 既存ソースをバッチごとに束ねる ファイル群を 2〜6 ファイルずつの「バッチ」に分け（ドメイン層／サービス層／UI 部品と一覧画面／詳細画面と cron など）、各バッチが参照する既存ファイルを 1 つのテキストに連結する。 ```sh dump(){ for f in "$@"; do echo "=====EXISTING FILE: $f====="; cat "$f"; echo; done; } dump lib/domain/x.ts tests/unit/domain/x.test.ts > ctx1.txt ``` 1 バッチの出力は max_tokens（DeepSeek は 8192）に収まる量にする。目安は合計 500 行以内。 ### 3. 生成スクリプト（`gen.mjs`） ```js // node gen.mjs import fs from 'node:fs'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; const S = path.dirname(fileURLToPath(import.meta.url)); const batch = Number(process.argv[2]); const SPEC = fs.readFileSync('<指示書のパス>', 'utf8'); const ctx = fs.readFileSync(path.join(S, `ctx${batch}.txt`), 'utf8'); const BATCHES = { 1: { files: ['lib/domain/x.ts', 'tests/unit/domain/x.test.ts'], note: '指示書の新規1・新規17に該当。' }, // ... }; const B = BATCHES[batch]; const header = `あなたは実装者です。指示書と既存ソースを読み、このバッチで指定されたファイルだけを完成形で出力してください。 出力形式（厳守・これ以外の文章は書かない）: =====FILE: <リポジトリルートからの相対パス>===== <ファイルの完全な内容> =====END===== ルール: - 出力するファイルは次の ${B.files.length} 個のみ: ${B.files.join(' / ')} - ${B.note} - 既存ファイルを変更する場合は差分ではなくファイル全体を出力する。既存のコメント・関数・import を落とさない。 - Markdown のコードフェンスは使わない。説明文も書かない。`; const prompt = `${header}\n\n# 指示書\n\n${SPEC}\n\n# 既存ソース\n\n${ctx}`; const key = process.env.DEEPSEEK_API_KEY; // 自前のキー解決に置き換える const res = await fetch('https://api.deepseek.com/chat/completions', { method: 'POST', headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'deepseek-chat', messages: [{ role: 'user', content: prompt }], max_tokens: 8192, temperature: 0.2 }), }); if (!res.ok) { console.error(`HTTP ${res.status}: ${await res.text()}`); process.exit(1); } const json = await res.json(); const text = json.choices?.[0]?.message?.content ?? ''; fs.writeFileSync(path.join(S, `out${batch}.md`), text); console.log(`batch ${batch}: finish=${json.choices?.[0]?.finish_reason} out=${json.usage?.completion_tokens}`); ``` `finish=length` なら途中切れ。バッチを割って再実行する。OpenAI 互換なら base URL とモデル名を替えるだけで Groq / OpenRouter / Kimi でも動く。 ### 4. 書き出しスクリプト（`split.mjs`、許可リストが肝） ```js // node split.mjs [--dry] import fs from 'node:fs'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; const S = path.dirname(fileURLToPath(import.meta.url)); const REPO = '<リポジトリのルート>'; const ALLOW = new Set(['lib/domain/x.ts', 'tests/unit/domain/x.test.ts' /* 指示書で列挙した全パス */]); const dry = process.argv.includes('--dry'); const text = fs.readFileSync(path.join(S, `out${process.argv[2]}.md`), 'utf8'); const re = /=====FILE:\s*(.+?)\s*=====\r?\n([\s\S]*?)\r?\n=====END=====/g; let m, n = 0; while ((m = re.exec(text))) { const rel = m[1].trim().replace(/^\.\//, '').replace(/\\/g, '/'); let body = m[2].replace(/^```[a-z]*\r?\n/, '').replace(/\r?\n```\s*$/, ''); if (!body.endsWith('\n')) body += '\n'; if (!ALLOW.has(rel)) { console.log(`SKIP (not allowed): ${rel}`); continue; } console.log(`${dry ? 'WOULD WRITE' : 'WRITE'}: ${rel} (${body.split('\n').length} lines)`); if (!dry) { fs.mkdirSync(path.dirname(path.join(REPO, rel)), { recursive: true }); fs.writeFileSync(path.join(REPO, rel), body); } n++; } console.log(`${n} files`); ``` **必ず `--dry` で一度パスと行数を見てから本書き出し**する。許可リスト外のパスは捨てる（モデルが勝手に別ファイルを足しても被害ゼロ）。 ### 5. 実行と検品（監督側） ```sh (node gen.mjs 1 & node gen.mjs 2 & node gen.mjs 3 & node gen.mjs 4 & wait) # 並列 for b in 1 2 3 4; do node split.mjs $b --dry; done for b in 1 2 3 4; do node split.mjs $b; done git status --porcelain # 列挙したファイル以外が変わっていないこと && && && ``` 検品は別のモデルに「`git diff` の `-` 行を全部見て、既存の内容が 1 行でも消えていないか」を見させる。全文出力方式は**既存コードの脱落**が最大のリスクなので、diff の削除行だけを重点的に見る。 ## 落とし穴 - `node gen.mjs` を `| tail` に繋ぐと出力がバッファされ、ハングと長考の区別がつかない。ファイルへリダイレクトして読む。 - ESM で絶対パスを import するときは `file:///C:/...` 形式。`C:/...` のままだと `ERR_UNSUPPORTED_ESM_URL_SCHEME`。 - tailwind-merge を使う UI では `border-danger` を足すと枠全体の色が置き換わる。左線だけなら `border-l-danger`。生成コードはこの手の「仕様どおりだが見た目が違う」を出すので、検品で拾う。 - `'use client'` の付け忘れ・付け過ぎは typecheck では出ない。「イベントハンドラがあるファイルだけ付ける」を指示書に書く。 ## 見積り | | トークン | |---|---| | ゼロから経路を試行錯誤して到達した場合 | 約 60,000 | | この指示書を読んで実行した場合 | 約 4,000 ＋ 生成分（1 ファイルあたり 1,000〜2,000） | ---