structured-coding-agent-output

Claude Code の出力を JSON Schema で検証し、構造化されたデータを取得するためのラッパーツールです。

特徴

- Zod スキーマ定義: TypeScript で型安全なスキーマを定義
- JSON Schema 自動生成: Zod から JSON Schema を自動生成
- 出力検証: Ajv による厳密な JSON Schema 検証
- リトライ機能: 検証失敗時の自動リトライ
- CLI サポート: コマンドラインから直接実行可能

インストール

$3

``bash
npm install structured-coding-agent-output
`

$3

`bash


HTTPS

npm install git+https://github.com/YOUR_USERNAME/structured-coding-agent-output.git

SSH

npm install git+ssh://git@github.com:YOUR_USERNAME/structured-coding-agent-output.git

特定のブランチやタグを指定

npm install git+https://github.com/YOUR_USERNAME/structured-coding-agent-output.git#main
npm install git+https://github.com/YOUR_USERNAME/structured-coding-agent-output.git#v1.0.0
`

$3

`bash


相対パス

npm install ../structured-coding-agent-output

絶対パス

npm install /path/to/structured-coding-agent-output

npm link を使用（開発時）

cd /path/to/structured-coding-agent-output
npm link

cd /path/to/your-project
npm link structured-coding-agent-output
`

$3

`bash
git clone https://github.com/YOUR_USERNAME/structured-coding-agent-output.git
cd structured-coding-agent-output
npm install
`

ビルド

`bash


TypeScript をコンパイル

npm run build

Zod スキーマから JSON Schema を生成

npm run generate:schemas
`

使い方

$3

`bash


ビルトインスキーマを使用

npx structured-claude -s opinion-review -p "このコードをレビューしてください: ..."

カスタム JSON Schema ファイルを使用

npx structured-claude -f ./my-schema.json -p "データを分析してください"

リトライ回数とタイムアウトを指定

npx structured-claude -s opinion-review -p "レビュー" -r 5 -t 60000

利用可能なスキーマ一覧を表示

npx structured-claude --list-schemas
`

$3

| オプション | 短縮形 | 説明 | デフォルト |
|-----------|--------|------|-----------|
| --schema | -s | 使用するビルトインスキーマ名 | - |
| --schema-file | -f | JSON Schema ファイルのパス | - |
| --prompt | -p | Claude Code に送信するプロンプト | (必須) |
| --retries | -r | 最大リトライ回数 | 3 |
| --timeout | -t | タイムアウト (ミリ秒) | 300000 |
| --list-schemas | - | 利用可能なスキーマ一覧を表示 | - |

$3

`typescript
import { createExecutor, createValidator } from 'structured-coding-agent-output';

// Executor を作成
const executor = createExecutor({
maxRetries: 3,
timeout: 300000,
});

// スキーマ名を指定して実行
const result = await executor.execute('このコードをレビューしてください', {
schema: 'opinion-review',
});

if (result.success) {
console.log('検証済みデータ:', result.data);
} else {
console.error('エラー:', result.error);
}

// カスタムスキーマファイルを使用
const result2 = await executor.execute('データを分析してください', {
schemaFile: './custom-schema.json',
});
`

$3

`typescript
import { createValidator } from 'structured-coding-agent-output';

const validator = createValidator('./schemas');

// スキーマ名で検証
const result = validator.validate('opinion-review', {
verdict: 'approve',
confidence: 85,
summary: 'コードは良好です',
});

if (result.valid) {
console.log('有効なデータ:', result.data);
} else {
console.log('検証エラー:', validator.formatErrors(result.errors));
}

// ファイルパスで検証
const result2 = validator.validateWithSchemaFile('./my-schema.json', data);
`

スキーマ定義

$3

コードレビューの結果を構造化するためのスキーマです。

`typescript
interface OpinionReview {
verdict: 'approve' | 'reject' | 'needs_revision'; // 判定結果
confidence: number; // 確信度 (0-100)
summary: string; // 概要
strengths?: string[]; // 強み (オプション)
weaknesses?: string[]; // 弱み (オプション)
suggestions?: string[]; // 提案 (オプション)
reasoning?: string; // 理由 (オプション)
}
`

$3

1. src/schemas/ に Zod スキーマを定義:

`typescript
// src/schemas/my-schema.ts
import { z } from 'zod';

export const MySchema = z.object({
title: z.string(),
score: z.number().min(0).max(100),
tags: z.array(z.string()).optional(),
});

export type MyData = z.infer;
`

2. src/schemas/index.ts にエクスポートを追加:

`typescript
import { MySchema } from './my-schema';

export const schemas = {
'opinion-review': OpinionReviewSchema,
'my-schema': MySchema, // 追加
} as const;
`

3. JSON Schema を生成:

`bash
npm run generate:schemas
`

出力フォーマット

Claude Code からの出力は以下の形式で構造化データを含める必要があります:

`markdown
`structured_output
{
"verdict": "approve",
"confidence": 85,
"summary": "コードは良好です"
}
`
`

または JSON コードブロック:

`markdown
`json
{
"verdict": "approve",
"confidence": 85,
"summary": "コードは良好です"
}
`
`

生の JSON も認識されます:

`json
{"verdict": "approve", "confidence": 85, "summary": "コードは良好です"}
`

API リファレンス

$3

`typescript
class ClaudeExecutor {
constructor(options?: ExecutorOptions);
execute(prompt: string, options?: ExecutorOptions): Promise;
extractStructuredOutput(output: string): unknown | null;
}

interface ExecutorOptions {
schema?: string; // スキーマ名
schemaFile?: string; // スキーマファイルパス
maxRetries?: number; // 最大リトライ回数
timeout?: number; // タイムアウト (ms)
validator?: SchemaValidator;
}

interface ExecutionResult {
success: boolean;
data?: unknown; // 検証済みデータ
rawOutput?: string; // Claude の生出力
error?: string; // エラーメッセージ
attempts: number; // 試行回数
}
`

$3

`typescript
class SchemaValidator {
constructor(schemasDir?: string);
loadSchema(schemaName: string): ValidateFunction;
loadSchemaFromFile(schemaFilePath: string): ValidateFunction;
validate(schemaName: string, data: unknown): ValidationResult;
validateWithSchemaFile(schemaFilePath: string, data: unknown): ValidationResult;
formatErrors(errors: ErrorObject[]): string;
}

interface ValidationResult {
valid: boolean;
data?: unknown;
errors?: ErrorObject[];
}
`

$3

`typescript
// Executor を作成
function createExecutor(options?: ExecutorOptions): ClaudeExecutor;

// Validator を作成
function createValidator(schemasDir?: string): SchemaValidator;
`

ディレクトリ構成

`
structured-coding-agent-output/
├── src/
│ ├── schemas/
│ │ ├── index.ts # スキーマエクスポート
│ │ └── opinion-review.ts # サンプルスキーマ
│ ├── wrapper/
│ │ ├── index.ts # wrapper エクスポート
│ │ ├── executor.ts # Claude Code 実行
│ │ └── validator.ts # Ajv 検証
│ └── index.ts # CLI エントリーポイント
├── scripts/
│ └── generate-schemas.ts # Zod → JSON Schema 生成
├── schemas/ # 生成された JSON Schema
│ └── opinion-review.json
├── __tests__/ # 単体テスト
├── package.json
├── tsconfig.json
└── jest.config.js
`

テスト

`bash


テスト実行

npm test

カバレッジ付きテスト

npm run test:coverage
``

依存関係

- zod: スキーマ定義
- zod-to-json-schema: Zod → JSON Schema 変換
- ajv: JSON Schema 検証
- commander: CLI パーサー

ライセンス

MIT