AIコーディングツールは内部でどう動くのか：Claude Codeのアーキテクチャを初心者向けに解説

// シンプルなエージェントの動き（疑似コード）
while (true) {                     // ← ずっと繰り返す（ループ＝同じ処理を繰り返すこと）

  // Step 1: AIにメッセージを送る
  const response = await claudeAPI.post('/v1/messages', {
    messages: messages,            // ← これまでの会話の記録（会話履歴）
    tools: toolDefinitions,        // ← AIが使えるツール（ファイル読み書き、コマンド実行など）
    model: 'claude-3-5-sonnet-20241022'
  });

  // Step 2: AIの返答を確認する
  if (response.stop_reason === 'tool_use') {
    // 「ツールを使いたい」という返答の場合 → ツールを実行する
    for (const toolUse of response.content) {
      const result = await executor.executeTool(
        toolUse.name,   // ← ツールの名前（例：「ファイルを読む」「コマンドを実行する」）
        toolUse.input   // ← ツールへの入力（例：「src/main.ts を読む」）
      );
      // ツールの実行結果をAIに返す（AIはこの結果を見て次の行動を決める）
      messages.push({
        type: 'tool_result',
        tool_use_id: toolUse.id,
        content: result
      });
    }
    // ループを続けて、またAIに聞く（AIはツール結果を踏まえて考え直す）
  } else {
    // 「答えが出た」という返答の場合 → ループを終了して結果を返す
    return response.content[0].text;
  }
}

// 権限チェックの流れ（4段階のチェックを順番に通過する）
async function canUseTool(toolName: string, input: unknown): Promise<boolean> {

  // 【段階1】入力が正しい形式かチェック（不正な入力を早めに弾く）
  try {
    tool.validateInput(input);
  } catch (e) {
    console.error(`不正な入力: ${toolName}`, e);
    return false;  // ← 不正な入力は実行しない
  }

  // 【段階2】Pre-Tool-Useフック（フック＝事前に実行する追加処理のこと）
  // settings.json で「このツールを使う前にこのスクリプトを実行する」と設定できる
  // 例：ログを取る、社内の承認システムに問い合わせる、など
  if (settings.hooks?.preToolUse) {
    const hookResult = await executeHook(settings.hooks.preToolUse);
    if (hookResult.action === 'deny')   return false;                       // フックが「禁止」と判断
    if (hookResult.action === 'modify') input = hookResult.modifiedInput;   // フックが入力を書き換え
  }

  // 【段階3】設定ファイルのルール確認
  // alwaysAllow（常に許可）→ alwaysDeny（常に拒否）→ alwaysAsk（毎回確認）の順で判定
  const rule = matchPermissionRule(toolName, input, settings.permissions);
  if (rule?.action === 'allow') return true;   // ← ルールで「許可」なら即OK
  if (rule?.action === 'deny')  return false;  // ← ルールで「拒否」なら即NG

  // 【段階4】ルールに当てはまらない場合はユーザーに確認（ポップアップ表示）
  const userApproval = await promptUser(`「${toolName}」を実行してもよいですか？`);
  if (userApproval.type === 'allowOnce')   return true;            // 今回だけ許可
  if (userApproval.type === 'allowAlways') {
    settings.permissions.alwaysAllowRules.push(rule);              // 今後は自動許可（ルールに追加）
    return true;
  }
  return false;  // ユーザーが拒否
}

// サブエージェント（専門担当のAI）を生成して別のタスクを任せる
async function forkSubagent(options: {
  goal: string;        // サブエージェントに何をやらせるか（例：「テストを書いて」）
  context?: string;    // 必要な背景情報（例：「このファイルはReactコンポーネントです」）
  spawnMode?: 'default' | 'fork' | 'worktree';  // 起動モード（後述）
}): Promise<SubagentResult> {

  // 新しい会話記録を作成（親エージェントの会話とは独立させる）
  // 人間で言えば「新しいチャット画面を開いて別の人に頼む」イメージ
  const subagentMessages: Message[] = [
    {
      type: 'user',
      content: `あなたは専門のサブエージェントです。\n目標: ${options.goal}\n背景: ${options.context}`
    }
  ];

  // spawnMode（起動モード）によって処理方法を変える
  if (options.spawnMode === 'fork') {
    // fork = 子プロセス（別プログラム）として起動
    // ファイルの読み込みキャッシュ（一時保存）だけ親と共有して効率化
    // → CPU処理が重いタスクに向いている
    const childProcess = await fork('./query.ts', {
      messages: subagentMessages,
      sharedFileCache: parentFileCache  // ← ファイルキャッシュは親子で共有（毎回ファイルを読み直さずに済む）
    });
    return await childProcess.run();

  } else if (options.spawnMode === 'worktree') {
    // worktree = git worktree（独立したフォルダ）で実行
    // ファイルの読み書きが多いタスク（リファクタリングなど）に向いている
    // 独立したフォルダなのでメインのコードに影響を与えない
    const worktreeDir = await createWorktree();  // ← 独立したフォルダを作成
    return await runAgentInWorktree(worktreeDir, subagentMessages);

  } else {
    // default = 同じプロセス内で実行（一番シンプル）
    // 軽量タスク・短時間で終わるタスクに向いている
    return await queryEngine.submitMessage(options.goal);
  }
}

// コンテキスト（会話記録）が満杯になりそうなとき、古い会話を要約して圧縮する
async function manageContextWindow(messages: Message[]): Promise<Message[]> {
  const tokenCount = estimateTokens(messages);  // ← 現在のトークン数を概算
  const maxTokens  = 200000;                    // ← Claude 3.5 Sonnetの上限（約20万トークン）

  // 上限の80%を超えたら圧縮開始（余裕を持って早めに対処する）
  if (tokenCount > maxTokens * 0.8) {
    const past   = messages.slice(0, -20);  // ← 古い会話（最後の20件より前をすべて取り出す）
    const recent = messages.slice(-20);     // ← 直近20件の会話（重要なので保持する）

    // 古い会話をAIに要約してもらう（「長い本の要約を作ってもらう」イメージ）
    const summary = await claude.messages.create({
      model: 'claude-3-5-sonnet-20241022',
      max_tokens: 2000,
      system: '会話の歴史を数文で要約してください。重要な情報は残してください。',
      messages: [{ role: 'user', content: `要約してください:\n${JSON.stringify(past)}` }]
    });

    // 圧縮後のメッセージ配列を作成：直近の会話 ＋ 古い会話の要約
    return [
      ...recent,  // ← 直近20件はそのまま
      {
        type: 'system',
        subtype: 'compact_boundary',  // ← 「ここから先は要約」というマーカー（目印）
        content: `[要約]\n${summary.content[0].text}\n[要約終わり]`
      }
    ];
  }

  return messages;  // 問題なければそのまま返す
}