**オピニオン・ドリブンで最小限に設計したコーディングエージェント構築から学んだこと**

2025‑11‑30

少ししかないが、私のものだ

pi‑ai と pi‑agent-core
そこにある。
四つの光…API
コンテキストハンドオフ
我々は多モデル世界で生きている
構造化されたツール結果分割
最小限のエージェントスキャフォールド
pi‑tui
二種類のTUI
保持モード UIDifferential レンダリング
pi‑coding-agent
まとめ

背景

過去三年間、私はLLMを補助的なコーディングに利用してきました。もしこの記事を読んでいるなら、あなたも同じ進化の道を歩んだことでしょう：ChatGPT へコードをコピー＆ペースト → Copilot のオートコンプリート（うまく機能しない）→ Cursor → Claude Code、Codex、Amp、Droid、opencode など新しいコーディングエージェントのハーネス。

私は主に Claude Code を使用していました。4 月に Cursor を一年半試した後、最初に手に入れたものです。当時は非常にシンプルで私のワークフローにピッタリでした。しかし最近では Claude Code は機能が多すぎて 80 % が不要になり、リリースごとにシステムプロンプトやツールが変わるためワークフローが壊れます。しかもちらつきがあります。

長年にわたりさまざまな複雑なエージェント（例：ブラウザ内で動く Sitegeist）を構築してきました。その中で「コンテキストエンジニアリング」が極めて重要だと学びました。モデルに渡すコンテキストを正確に制御することで、特にコード生成時の出力が向上します。既存ハーネスは背後で注入した情報を UI に表示せず、設定が難しいです。

さらに、入力・出力などインタラクションの各側面を自動化し、セッション形式を簡潔に文書化できるようにしたいと考えました。多くのハーネスは API がオーガニックに進化して重たく、開発者体験が悪化しています。

自己構築の理由

自分でコードを書くことで「何を必要か」を明確にできるので、以下のモジュールを作成しました：

「必要なものだけ作る」という哲学に基づき、不要な機能は実装していません。

pi‑ai

pi‑ai は 4 つの主要 API（OpenAI Completions/Responses, Anthropic Messages, Google Gemini）を抽象化します。プロバイダー固有の挙動（例：

store

max_tokens

reasoning_effort

コンテキストハンドオフ

プロバイダー間のコンテキストは「思考トレース」を

<thinking></thinking>

import { getModel, complete, Context } from '@mariozechner/pi-ai';

const claude = getModel('anthropic', 'claude-sonnet-4-5');
let context: Context = { messages: [] };

context.messages.push({ role: 'user', content: 'What is 25 * 18?' });
const claudeResponse = await complete(claude, context, { thinkingEnabled: true });
context.messages.push(claudeResponse);

const gpt = getModel('openai', 'gpt-5.1-codex');
context.messages.push({ role: 'user', content: 'Is that correct?' });
const gptResponse = await complete(gpt, context);

ストリーミング & アボート

const model = getModel('openai', 'gpt-5.1-codex');
const controller = new AbortController();
setTimeout(() => controller.abort(), 2000);

for await (const event of stream(model, { messages: [{ role: 'user', content: 'Write a long story' }] }, { signal: controller.signal })) {
  if (event.type === 'text_delta') process.stdout.write(event.delta);
}

ツール結果の分離

ツールは LLM 用テキストと UI 表示用データを同時に返せます。例：

const weatherTool: AgentTool<typeof weatherSchema, { temp: number }> = {
  name: 'get_weather',
  parameters: weatherSchema,
  execute: async (_, args) => ({
    output: `Temperature in ${args.city}: ${Math.round(Math.random() * 30)}°C`,
    details: { temp: Math.round(Math.random() * 30) }
  })
};

pi‑agent-core

エージェントループは「メッセージ → ツール呼び出し → 結果を LLM に戻す」まで自動で繰り返します。最大ステップ制御は実装していませんが、必要なら

Agent

pi‑tui

差分レンダリングアルゴリズム：

1. 初回：全行を書き出す
2. 幅変更時：スクリーンをクリアして再描画
3. 通常更新：最初に変わった行まで移動し、そこから再描画

フリッカー防止のため、CSI

?2026h

?2026l

pi‑coding-agent

• Windows, Linux, macOS（Node.js があれば）
• マルチプロバイダー・モデル切替
• セッション管理：続行、再開、ブランチ
• プロジェクトコンテキストファイル（AGENTS.md）を階層的にロード
• スラッシュコマンドで共通操作
• カスタムテーマ & ライブリロード
• エディタ：ファイル検索・パス補完・ドラッグ＆ドロップ・複数行貼り付け
• 画像サポート（ビジョン対応モデル）
• HTML 出力、ヘッドレス JSON ストリーミング
• コスト・トークン追跡

システムプロンプト（例）

You are an expert coding assistant. You help users with coding tasks by reading files, executing commands, editing code, and writing new files.
...
Documentation: /path/to/README.md

ツール定義

• read – ファイル読み取り
• write – 書き込み（新規または上書き）
• edit – 正確なテキスト置換
• bash – シェルコマンド実行

省略した機能

bash

ベンチマーク

Terminal‑Bench 2.0 により Claude Opus 4.5 と他ハーネス（Codex, Cursor, Windsurf 等）を比較。結果は 2025年12月現在のリーダーボードに掲載されています。

まとめ

pi は「必要最低限」で構築したエージェントハーネスです。コンテキスト制御、差分レンダリング、ツール結果分離などを実装し、日々の作業で高い信頼性と速度を提供しています。追加機能（圧縮・ツール結果ストリーム等）は検討中ですが、現時点では十分です。

貢献歓迎ですが、プロジェクトは集中管理を重視します。要件に合わない場合はフォークしていただければ幸いです。ご質問やフィードバックはお気軽にどうぞ。