7. Artifact — AIと人間が共通して参照する成果物・判断材料
Artifactとは
Artifactとは、AIと人間が共通して参照する成果物・判断材料です。 たとえば、仕様書、設計書、API契約、DBスキーマ、テストなどです。
重要なのは、会話ログではなくファイルとして残るものを中心にすることです。
Product ArtifactsとControl Artifacts
Product Artifacts
| Artifact | 役割 |
|---|---|
| 設計ドキュメント | 仕様の機械可読な正本 |
| 仕様書 | 人間が読む自然言語仕様 |
| OpenAPI定義 | API契約の正本 |
| DBスキーマ | 現在のDBスキーマの正本 |
| マイグレーション | DB変更履歴の正本 |
| IaC定義 | インフラ構成の正本 |
| 生成コード | OpenAPIから生成される型・ルート |
| テスト | 仕様を検証する証拠 |
Control Artifacts
| Artifact | 役割 |
|---|---|
| DSL定義ファイル | 制御構造全体の入口 |
| エージェント定義 | エージェントの役割・権限 |
| 成果物定義 | 成果物の所有者・状態遷移 |
| ワークフロー定義 | フェーズとゲート |
| ガードレイル定義 | 守るべき制約 |
| ポリシー定義 | block/warn/shadow |
| バインディング定義 | エディタ・Gitでの適用方法 |
| ルールファイル | エージェント向けルール |
| Hook | 自動生成された物理的制御 |
SSoTとは
SSoTはSingle Source of Truth、つまり「正しい情報はここにある」という場所です。
悪い例:
- 仕様は仕様書にも書いてある
- API YAMLにも似たことが書いてある
- テストにも別の前提がある
- 実装はさらに違う
良い例:
- 仕様IDは設計ドキュメントが正本
- API契約はOpenAPIが正本
- DB構造はスキーマ/マイグレーションが正本
- 生成コードは手で直さない
Dual-Write
本方式では、仕様を2つの形式で持ちます。
| 形式 | 目的 |
|---|---|
| 自然言語仕様 | 人間が読む |
| 機械可読データ | ツールが検証する |
これは二重管理に見えますが、目的が違います。
- 人間には自然言語が必要
- AIとToolchainには機械可読データが必要
その代わり、両者の整合性を検証します。
Traceability
仕様からテストまでをつなげます。
これにより、次が言えます。
- このテストはどの仕様を検証しているか
- この仕様はテストされているか
- この仕様を変えたら、どのテストが影響するか
Artifactが重要な理由
AIは会話だけに依存すると、文脈を忘れたり、別セッションで再現できなかったりします。
Artifactとしてリポジトリに残せば、以下が可能になります。
結論
Artifactは単なるドキュメントではありません。
AI駆動開発では、Artifactが判断材料・証拠・制御対象になります。