目次
“フォーマット迷子”がプロジェクトを遅らせる
実装推進会議で最も時間を奪うのは、設計ではなく*解釈違い*です。
特に生成AIが返すレスポンスを次のシステムへ渡す際、曖昧なフォーマットは即バグにつながります。
だからこそ、開発初期に出力フォーマットを**言語化**し、API仕様書に落とし込むことが不可欠です。
フォーマット指定のゴールは“誤解ゼロ”
人ではなくマシンが読むと割り切り、シンプルかつ決め打ちで書くのが鉄則。
- *固定キー名*と順序を明記
- エンコーディング・改行コードを統一
- 想定外入力時の既定値・エラー仕様をセット
この三点を守るだけで、後工程の保守コストは劇的に下がります。
JSONを使うときのベストプラクティス
JSONは階層構造が自由な反面、自由すぎて破綻しやすい。
*深さは3階層以内*を目安にカプセル化し、読み取り側をシンプルにします。
- 日付はISO-8601に統一
- nullを許容するキーは別途リスト化
- 数値型は”string”で包まない
さらに、スキーマ定義（JSON Schema）をCIでバリデーションすると手戻りはほぼゼロになります。
CSVを選ぶなら“列固定”が命
CSVは人の目に優しい反面、可変列を許すと一瞬で崩壊します。
ヘッダー行とカンマ区切りのエスケープ規則を先にFIXし、サンプルファイルを共有してください。
- 列追加は末尾のみ
- 改行を含むセルは禁止
- 数値・日付はフォーマットをコメントに明示
*読みやすさより解析しやすさ*を優先しましょう。
HTMLレスポンスを扱うコツ
AIがMarkdownやHTMLで返すケースも増えました。
スクレイピングと同じく、*構造化の仕込み*がないHTMLは扱い辛い。
- タグの階層を浅くし、class名を固定
- 装飾はCSS、構造はHTMLに分離
- DOMテストで属性名の変更を検知
フロント側で再利用する場合も、同じ構造を保てばスタイル替えだけで済みます。
統合テストで“想定外”を先に潰す
フォーマットを固めたら、異常値テストを自動化します。
- 空文字・極端な長さ・マルチバイト混入
- 無効な日付・ゼロ除算などの論理エラー
- ネットワーク遅延・タイムアウト
*観測できないバグは直せない*ので、ログは整形フォーマットでクラウドに集約しておきましょう。
まとめと次の一歩
出力フォーマットを明文化し、テストで守る体制が整えば、API連携は*自走*します。
次のフェーズではOpenAPIやAsyncAPIと組み合わせ、ドキュメントとコードを同期させるとさらに運用が楽になります。
最後にもう一度──フォーマットは“仕様書の一行目”から書き始めてください。
コメント