Structured output wrapper for Claude Code with JSON Schema validation
npm install structured-coding-agent-outputClaude Code の出力を JSON Schema で検証し、構造化されたデータを取得するためのラッパーツールです。
- Zod スキーマ定義: TypeScript で型安全なスキーマを定義
- JSON Schema 自動生成: Zod から JSON Schema を自動生成
- 出力検証: Ajv による厳密な JSON Schema 検証
- リトライ機能: 検証失敗時の自動リトライ
- CLI サポート: コマンドラインから直接実行可能
``bash`
npm install structured-coding-agent-output
`bashHTTPS
npm install git+https://github.com/YOUR_USERNAME/structured-coding-agent-output.git
$3
`bash
相対パス
npm install ../structured-coding-agent-output絶対パス
npm install /path/to/structured-coding-agent-outputnpm link を使用(開発時)
cd /path/to/structured-coding-agent-output
npm linkcd /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 buildZod スキーマから 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