mcpField
D
doc-ctr

doc-ctr

github.com/vladm3105開発1748 回インストール1 日前に更新
リポジトリ

doc-ctr について

SDDワークフローでデータ契約を作成し、APIインターフェースとデータスキーマをMarkdownとYAMLのペアで定義するスキルです。テンプレート、トレーサビリティ規則、品質ゲートを備え、要件から技術仕様への移行を支援します。

主な機能

  1. 01MarkdownとYAMLのペアで契約を作成
  2. 02APIとデータスキーマを定義
  3. 03OpenAPI 3.0とJSON Schemaに対応
  4. 04トレーサビリティとID規則を適用
  5. 05ドキュメントの品質ゲートを確認

活用シーン

  1. 01上流要件に基づくAPI契約の定義
  2. 02チームやサービス間でのインターフェース共有
  3. 03技術仕様に向けた契約ドキュメントの準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-ctr

インストール後、Claude Code で/doc-ctrを入力して読み込まれたか確認します。

詳細

doc-ctr

目的

**データコントラクト（CTR）**を作成します。SDD ワークフローにおける任意のレイヤー 8 の成果物であり、マークダウンと YAML の二重ファイル形式を使用して、API コントラクト、データスキーマ、インターフェース仕様を定義します。

レイヤー：8（任意）

上流：BRD（レイヤー 1）、PRD（レイヤー 2）、EARS（レイヤー 3）、BDD（レイヤー 4）、ADR（レイヤー 5）、SYS（レイヤー 6）、REQ（レイヤー 7）

下流の成果物：SPEC（レイヤー 9）、TSPEC（レイヤー 10）、TASKS（レイヤー 11）、Code（レイヤー 12）

前提条件

上流成果物の確認（重要）

このドキュメントを作成する前に、必ず次の作業を行ってください。

  1. 既存の上流成果物を一覧表示します。

    ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ docs/05_ADR/ docs/06_SYS/ docs/07_REQ/ 2>/dev/null

  2. トレーサビリティタグでは、実在するドキュメントのみを参照します

  3. 上流成果物の種類が実際に存在しない場合に限り、nullを使用します

  4. BRD-XXXやTBDのようなプレースホルダーは決して使用しません

  5. 不足している上流成果物は作成しません。代わりに、その機能をスキップします

CTR を作成する前に、次の内容を読んでください。

  1. 共有標準：.claude/skills/doc-flow/SHARED_CONTENT.md
  2. 上流の REQ：アトミックな要件を読みます（特にセクション 3：インターフェース仕様、セクション 4：データスキーマ）
  3. テンプレート：ai_dev_ssd_flow/08_CTR/CTR-MVP-TEMPLATE.mdとCTR-MVP-TEMPLATE.yaml
  4. 作成ルール：ai_dev_ssd_flow/08_CTR/CTR-MVP-TEMPLATE.md
  5. 検証ルール：ai_dev_ssd_flow/08_CTR/CTR_MVP_SCHEMA.yaml
  6. 検証スクリプト：./ai_dev_flow/scripts/validate_ctr.sh

予約 ID の免除（CTR-00_*）

対象範囲：予約 ID 000のドキュメントは、検証が全面的に免除されます。

パターン：CTR-00_*.md、CTR-00_*.yaml

ドキュメントの種類：

  • インデックスドキュメント（CTR-00_index.md）
  • トレーサビリティマトリクスのテンプレート（CTR-00_TRACEABILITY_MATRIX-TEMPLATE.md）
  • 用語集、レジストリ、チェックリスト

理由：予約 ID 000 のドキュメントは、フレームワークの基盤（インデックス、テンプレート、参考資料）であり、トレーサビリティや品質ゲートが必要なプロジェクト成果物ではありません。

検証時の動作：ファイル名がCTR-00_*パターンに一致する場合、すべてのチェックをスキップします。

このスキルを使用するタイミング

次の場合にdoc-ctrを使用します。

  • BRD から REQ（レイヤー 1～7）までを完了している
  • API コントラクトまたはデータスキーマを定義する必要がある
  • 複数のチームやサービスで共有コントラクトが必要である
  • マイクロサービスまたは分散システムを構築している
  • REQ セクション 3（インターフェース仕様）に正式なコントラクトが必要である
  • このレイヤーは任意（レイヤー 8）です。コントラクトがシンプルな場合はスキップしてください

CTR 固有のガイダンス

1. 必須の二重ファイル形式

各コントラクトには、2 つのファイルが必要です（必須の二重ファイル形式：.mdファイルと、それに対応する.yamlファイル）。

マークダウンファイル（.md）：

  • ドキュメント管理セクション
  • コントラクトの概要
  • ビジネスコンテキスト
  • 使用例
  • トレーサビリティ

YAML ファイル（.yaml）：

  • OpenAPI 3.0 または JSON Schema
  • 正式なコントラクト定義
  • 検証ルール
  • ペイロードの例

例：

ai_dev_ssd_flow/08_CTR/CTR-01_data_validation.md
ai_dev_ssd_flow/08_CTR/CTR-01_data_validation.yaml
2. ドキュメント管理フィールド（必須 9 項目）
フィールド必須説明
CTR IDはいCTR-NN 形式
タイトルはいコントラクト名
ステータスはいDraft/In Review/Active/Deprecated
バージョンはいセマンティックバージョン（Major.Minor.Patch）
作成日はいYYYY-MM-DD
作成者はいドキュメントの作成者
オーナーはいコントラクトのオーナー
最終更新日はいYYYY-MM-DD
SPEC 対応スコアはい✅ NN%（目標：≥90%）
3. 必須セクション（Markdown ファイル）

ドキュメント管理（必須 — すべての番号付きセクションより前に配置）

必須セクション（12 セクションの MVP 構成）：

#セクション目的
1ドキュメント管理メタデータ、SPEC 準備度スコア
2コンテキスト問題の説明、制約、トレードオフ
3契約の定義インターフェースの概要、関係者、パターン
4要件への対応上位の要件とのリンク
5インターフェース定義スキーマの参照、エンドポイント
6エラー処理エラーコード、障害モード
7品質属性パフォーマンス、セキュリティ、信頼性
8バージョン管理戦略バージョンポリシー、互換性
9例リクエスト／レスポンスのペア
10検証契約テスト、BDD 参照
11トレーサビリティ上流／下流、タグ
12参照内部／外部リンク

任意の付録：

  • 付録 A：検討した代替案
  • 付録 B：実装に関する注記
4. 要素 ID の形式（必須）

パターン：CTR.{DOC_NUM}.{HASH}（3 セグメント、ドット区切り）

要素の種類コード例
インターフェース16CTR.02.1601
データモデル17CTR.02.1701
契約条項20CTR.02.2001

廃止されたパターン — 旧形式は使用しないでください：

  • INT-XXX — 代わりに CTR.NN.16.SS を使用
  • MODEL-XXX — 代わりに CTR.NN.17.SS を使用
  • CLAUSE-XXX — 代わりに CTR.NN.20.SS を使用
  • IF-XXX — 代わりに CTR.NN.16.SS を使用
  • DM-XXX — 代わりに CTR.NN.17.SS を使用
  • CC-XXX — 代わりに CTR.NN.20.SS を使用

参照：ID_NAMING_STANDARDS.md - 相互参照リンク形式

5. YAML 契約形式

OpenAPI 3.0 形式（API 用）：

openapi: 3.0.3
info:
  title: Data Validation API
  version: 1.0.0
  description: Contract for data validation

paths:
  /api/v1/data/validate:
    post:
      summary: Validate data record
      operationId: validateDataRecord
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataRequest'
      responses:
        '200':
          description: Validation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    DataRequest:
      type: object
      required:
        - record_type
        - record_id
        - data
        - account_id
      properties:
        record_type:
          type: string
          pattern: ^[A-Z]{1,10}$
          example: "METRIC"
        record_id:
          type: string
          format: uuid
          example: "abc123"
        data:
          type: object
          example: {}
        account_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"

    ValidationResponse:
      type: object
      required:
        - valid
        - order_id
      properties:
        valid:
          type: boolean
          example: true
        order_id:
          type: string
          format: uuid
          example: "987f6543-e21c-43d2-b654-426614174111"
        warnings:
          type: array
          items:
            type: string
          example: ["Price near market close"]

    ErrorResponse:
      type: object
      required:
        - error_code
        - message
      properties:
        error_code:
          type: string
          example: "INVALID_SYMBOL"
        message:
          type: string
          example: "Symbol 'XYZ' not found in approved list"
        details:
          type: object
          additionalProperties: true

JSON Schema 形式（データモデル用）：

$schema: "http://json-schema.org/draft-07/schema#"
name: DataProcessingConfig
description: Configuration schema for data processing

type: object
required:
  - max_batch_size
  - timeout_seconds
  - check_frequency

properties:
  max_batch_size:
    type: integer
    minimum: 1
    maximum: 10000
    description: Maximum records per batch
    example: 1000

  timeout_seconds:
    type: integer
    minimum: 1
    maximum: 300
    description: Processing timeout in seconds
    example: 60

  check_frequency:
    type: string
    enum: ["realtime", "1min", "5min", "15min"]
    description: How often to check processing status
    example: "1min"

  alert_threshold:
    type: number
    minimum: 0
    maximum: 1.0
    description: Alert when queue depth exceeds this fraction
    default: 0.80
    example: 0.80
6. 使用例セクション

形式：

## Usage Examples

### Example 1: Successful Validation

**Request**:
```json
{
  "record_type": "METRIC",
  "record_id": "abc123",
  "data": {"value": 100},
  "account_id": "123e4567-e89b-12d3-a456-426614174000"
}

レスポンス：

{
  "valid": true,
  "order_id": "987f6543-e21c-43d2-b654-426614174111",
  "warnings": []
}
例 2：無効なレコードタイプ

リクエスト：

{
  "record_type": "invalid",
  "record_id": "abc123",
  "data": {"value": 100},
  "account_id": "123e4567-e89b-12d3-a456-426614174000"
}

レスポンス（400 Bad Request）：

{
  "error_code": "INVALID_RECORD_TYPE",
  "message": "Record type 'invalid' not found in approved list",
  "details": {
    "record_type": "invalid",
    "approved_types": ["METRIC", "EVENT", "LOG"]
  }
}


### 7. Contract Versioning

**Semantic Versioning**: Major.Minor.Patch

**Version Policy**:
- **Major**: Breaking changes (incompatible)
- **Minor**: New features (backward compatible)
- **Patch**: Bug fixes (backward compatible)

**Example**:
```yaml
openapi: 3.0.3
info:
  title: Data Validation API
  version: 2.1.0  # Major.Minor.Patch
  description: |
    Version 2.1.0 (2025-01-15)
    - Added: optional 'warnings' field in response (minor)
    - Fixed: validation error for edge case data (patch)

    Breaking changes from v1.x:
    - Changed: account_id now requires UUID format (was string)
8. SPEC 準備度のスコアリングシステム

目的：CTR の成熟度と、技術仕様（SPEC）フェーズへ進む準備状況を測定します。

ドキュメント管理での形式：

| **SPEC-Ready Score** | ✅ 95% (Target: ≥90%) |

ステータスと SPEC 準備度スコアの対応：

SPEC 準備度スコア必須ステータス
≥90%Active
70-89%In Review
<70%Draft

スコアリング基準：

  • スキーマの完全性（35%）：すべてのエンドポイント／モデルが定義され、JSON Schema／OpenAPI の検証に合格し、例が提供されていること
  • エラー処理（25%）：すべてのエラーコードが文書化され、再試行戦略が指定され、障害モードが網羅されていること
  • 品質属性（20%）：パフォーマンス目標、SLA 要件、冪等性が指定されていること
  • トレーサビリティ（10%）：上流の REQ／ADR がリンクされ、利用側／提供側が特定されていること
  • ドキュメント（10%）：使用例、バージョン管理ポリシー、非推奨化戦略が記載されていること

品質ゲート：スコアが 90% 未満の場合、SPEC 成果物の作成はブロックされます。

9. サービスタイプ別のディレクトリ構成

目的：大規模プロジェクト（契約が 30 件以上）で、サービスタイプごとに契約を整理します。

構成：

CTR/
├── agents/              # Agent-to-agent communication
├── mcp/                 # MCP server contracts
├── infra/               # Infrastructure services
└── shared/              # Cross-cutting contracts

使用するタイミング：

  • 契約が 10 件未満：フラットなディレクトリ
  • 契約が 10～30 件：サブディレクトリは任意
  • 契約が 30 件以上：サブディレクトリが必須

推奨事項：最初はフラットな構成にし、サービスタイプごとに契約が 3 件以上になった時点でサブディレクトリへ移行します。

タグ形式の規約（意図的な設計）

SDD フレームワークでは、相互参照に 2 種類の異なる表記体系を使用します。

表記形式成果物目的
ハイフンTYPE-NNADR、SPEC、CTR技術成果物。ファイル／ドキュメントへの参照
ドットTYPE.NN.xxxxBRD、PRD、EARS、BDD、SYS、REQ、IMPL、TASKS階層型成果物。ドキュメント内の要素への参照

重要な違い：

  • @adr: ADR-033 → ドキュメント ADR-033_risk_limit_enforcement.md を指します
  • @brd: BRD.17.0101 → ドキュメント BRD-017.md 内の要素 01.01 を指します

統一要素 ID 形式（必須）

階層型要件（BRD、PRD、EARS、BDD、SYS、REQ、IMPL）の場合：

  • 必ず使用：TYPE.NN.xxxx（ドット区切りの 3 セグメント統一形式）
  • 使用禁止：TYPE-NN:NNN（コロン区切り。非推奨）
  • 使用禁止：TYPE.NN.TT.SS（旧 4 セグメント形式。非推奨）

例：

  • @brd: BRD.17.0101 ✅
  • @brd: BRD.017.001 ❌（旧 3 セグメント形式）

累積タグ付けの要件

レイヤー 8（CTR）：レイヤー 1～7（BRD から REQ まで）のタグを含める必要があります

タグ数：7 個のタグ

累積タグの要素タイプコード：

タグ成果物要素タイプコード
@brdBRDビジネス要件01
@prdPRD製品機能07
@earsEARSEARS ステートメント25
@bddBDDシナリオ14
@adrADRドキュメント参照（ハイフン表記）
@sysSYSシステム要件26
@reqREQアトミック要件27

形式：

## Traceability

**Required Tags** (Cumulative Tagging Hierarchy - Layer 8):
```markdown
@brd: BRD.01.0103
@prd: PRD.01.0702
@ears: EARS.01.2501
@bdd: BDD.01.1401
@adr: ADR-033, ADR-045
@sys: SYS.01.2601
@req: REQ.01.2703

上流／下流の成果物

上流のソース：

  • BRD（レイヤー 1）- ビジネス要件
  • PRD（レイヤー 2）- 製品機能
  • EARS（レイヤー 3）- 形式的な要件
  • BDD（レイヤー 4）- テストシナリオ
  • ADR（レイヤー 5）- アーキテクチャ上の決定
  • SYS（レイヤー 6）- システム要件
  • REQ（レイヤー 7）- アトミック要件（主要なソース。特にセクション 3）

下流の成果物：

  • SPEC（レイヤー 9）- 技術仕様
  • TSPEC（レイヤー 10）- テスト仕様
  • TASKS（レイヤー 11）- タスクの内訳
  • コード（レイヤー 12）- 実装コード

同種ドキュメント間の関係（条件付き）：

  • @related-ctr: CTR-NN - API コンテキストを共有する CTR
  • @depends-ctr: CTR-NN - 先に完了する必要がある CTR

検証チェック

Tier 1：エラー（ブロック対象）
チェック説明
CHECK 1必須のドキュメント管理フィールド（9 項目）
CHECK 2二重ファイル形式（.md と .yaml の両方が存在する）
CHECK 3SPEC 準備完了スコアの形式（✅ 絵文字 + パーセンテージ + 目標値）
CHECK 4YAML スキーマ検証（OpenAPI／JSON Schema が有効）
CHECK 5累積タグ付け（上流タグ 7～8 個）
CHECK 6要素 ID 形式（CTR.NN.xxxx）
Tier 2：警告（推奨）
チェック説明
CHECK 7使用例（リクエスト／レスポンスのペア）
CHECK 8エラー処理（エラーコードが文書化されている）
CHECK 9バージョン管理ポリシー（セマンティックバージョニング）
CHECK 10検証ルール（スキーマ検証が指定されている）
Tier 3：情報
チェック説明
CHECK 11ディレクトリ構成（30 件以上のコントラクトにはサブディレクトリを使用）
CHECK 12利用者／提供者が特定されている
コミット前フック

CTR の検証は、コミット前フックによって自動的に強制されます。

# .pre-commit-config.yaml
- id: ctr-core-validator
  name: Validate CTR core checks (validator, framework library)
  entry: bash ai_dev_ssd_flow/08_CTR/scripts/ctr_core_validator_hook.sh ai_dev_ssd_flow/08_CTR
  language: system
  pass_filenames: false
  stages: [pre-commit]

- id: ctr-quality-gate
  name: Validate CTR quality gates
  entry: bash ai_dev_ssd_flow/08_CTR/scripts/ctr_quality_gate_hook.sh ai_dev_ssd_flow/08_CTR
  language: system
  pass_filenames: false
  stages: [pre-commit]

- id: ctr-spec-ready-score
  name: Validate CTR SPEC-Ready score (≥90%)
  entry: bash ai_dev_ssd_flow/08_CTR/scripts/ctr_spec_ready_score_hook.sh ai_dev_ssd_flow/08_CTR
  language: system
  pass_filenames: false
  stages: [pre-commit]

適用される品質ゲート:

  • ✅ デュアルファイル形式（.md と .yaml のペアファイル）
  • ✅ Active ステータスでは SPEC-Ready スコア ≥90%
  • ✅ OpenAPI 3.0 または JSON Schema の検証
  • ✅ 文書管理フィールド（必須フィールド 9 項目）
  • ✅ 累積タグ付け（@brd から @req まで、7 個のタグ）
  • ✅ 要素 ID の形式（インターフェース／モデル／条項には CTR.NN.xxxx）
  • ✅ 使用例（リクエスト／レスポンスのペア）
  • ✅ エラー処理の仕様
  • ✅ バージョン管理ポリシー（セマンティックバージョニング）
  • ✅ 検証ルールの文書化
  • ✅ コンシューマー／プロバイダーの識別
  • ✅ 品質属性（パフォーマンス、セキュリティ、信頼性）

フックスクリプト:

  • ctr_core_validator_hook.sh - CTR のコア構造とデュアルファイルの検証
  • ctr_quality_gate_hook.sh - 完全性に関する品質ゲートのチェック
  • ctr_spec_ready_score_hook.sh - SPEC-Ready スコアの計算（≥90% が必須）

作成プロセス

ステップ 1: 上流の成果物を読む

REQ のセクション 3（インターフェース仕様）とセクション 4（データスキーマ）に注目します。

ステップ 2: ID 番号を確保する

ai_dev_ssd_flow/08_CTR/ で次に利用可能な ID 番号を確認します。

ID 番号の付番規則: 2 桁から始め、必要な場合にのみ桁数を増やします。

  • ✅ 正しい例: CTR-01、CTR-99、CTR-102
  • ❌ 誤った例: CTR-001、CTR-009（先頭に余分なゼロを付ける必要はありません）
ステップ 3: CTR ファイルを作成する（デュアル形式）

ネストフォルダーのルール（必須）: 文書のサイズにかかわらず、すべての CTR 文書でネストフォルダーを使用する必要があります。

場所:

  • 標準: docs/08_CTR/CTR-NN_{slug}/CTR-NN_{slug}.md + .yaml
  • サービスベース: docs/08_CTR/{service_type}/CTR-NN_{slug}/CTR-NN_{slug}.md + .yaml

フォルダーのオンデマンド作成: 保存する前に、対象ディレクトリを作成します。

# Create nested folder (ALWAYS required)
mkdir -p docs/08_CTR/CTR-NN_{slug}/
# OR for service-type subdirectory
mkdir -p docs/08_CTR/{service_type}/CTR-NN_{slug}/

サービスタイプ（契約が 10 件以上の場合）:

  • agents/ - エージェント間の通信
  • mcp/ - MCP サーバーの契約
  • infra/ - インフラストラクチャサービス
  • shared/ - 横断的な契約

例:

  • 標準: docs/08_CTR/CTR-01_data_validation/CTR-01_data_validation.md + .yaml
  • サービスベース: docs/08_CTR/agents/CTR-01_data_validation/CTR-01_data_validation.md + .yaml

重要: ネストしたフォルダー構造を使わずに、docs/08_CTR/ 直下に CTR ファイルを作成しないでください。

ステップ 4: 文書管理セクションに入力する（Markdown）

SPEC-Ready スコアを含む、必須フィールド 9 項目すべてに入力します。

ステップ 5: 契約の概要を記述する（Markdown）

目的、スコープ、バージョンを要約します。

ステップ 6: YAML 契約を定義する

形式を選びます。

  • REST API には OpenAPI 3.0
  • データモデル には JSON Schema
  • イベント駆動システム には AsyncAPI（該当する場合）
ステップ 7: 使用例を追加する（Markdown）

説明を添えて、リクエスト／レスポンスの例を示します。

ステップ 8: 検証ルールを文書化する（Markdown）

スキーマ検証とビジネスルールを説明します。

ステップ 9: エラー処理を指定する（Markdown）

エラーコードとレスポンスを文書化します。

ステップ 10: 累積タグを追加する

上流のタグをすべて（@brd から @req/impl まで、7～8 個）含めます。

ステップ 11: トレーサビリティマトリックスを作成／更新する

必須: ai_dev_ssd_flow/08_CTR/CTR-00_TRACEABILITY_MATRIX-TEMPLATE.md を更新します。

ステップ 12: CTR を検証する
# YAML schema validation
yamllint ai_dev_ssd_flow/08_CTR/CTR-01_*.yaml

# OpenAPI validation
openapi-spec-validator ai_dev_ssd_flow/08_CTR/CTR-01_*.yaml

# Cumulative tagging
python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact CTR-01 --expected-layers brd,prd,ears,bdd,adr,sys,req,impl --strict
ステップ 13: 変更をコミットする

両方のファイル（.md と .yaml）およびトレーサビリティマトリックスをコミットします。

検証

自動検証
# Quality gates
scripts/validate_quality_gates.sh ai_dev_ssd_flow/08_CTR/CTR-01_*.md

# YAML validation
yamllint ai_dev_ssd_flow/08_CTR/CTR-01_*.yaml

# OpenAPI validation (if using OpenAPI)
openapi-spec-validator ai_dev_ssd_flow/08_CTR/CTR-01_*.yaml

# CTR-specific validation (includes dual-file check)
./ai_dev_flow/scripts/validate_ctr.sh CTR-01

# Cumulative tagging
python ai_dev_flow/scripts/validate_tags_against_docs.py \
  --artifact CTR-01 \
  --expected-layers brd,prd,ears,bdd,adr,sys,req,impl \
  --strict
手動チェックリスト
  • 両方のファイルを作成した（.md と .yaml）
  • 文書管理が完了している（9 項目）
  • SPEC-Ready スコアの形式が正しい（✅ NN% (Target: ≥90%)）
  • 契約の概要が明確である
  • ビジネスコンテキストで理由を説明している（REQ へのリンク）
  • YAML 契約が有効である（OpenAPI／JSON Schema）
  • 使用例が包括的である
  • エラー処理が文書化されている
  • 検証ルールが指定されている
  • バージョン番号がセマンティックバージョニング形式である（Major.Minor.Patch）
  • 累積タグ: @brd から @req/impl まで（7～8 個のタグ）
  • 要素 ID が CTR.NN.xxxx 形式を使用している
  • トレーサビリティマトリックスが更新されている
図の標準

すべての図には、必ず Mermaid 構文を使用してください。テキストベースの図（ASCII アート、罫線文字）は禁止されています。 参照：ai_dev_ssd_flow/DIAGRAM_STANDARDS.md および mermaid-gen スキル。

よくある落とし穴

  1. ファイルが1つだけ：.md ファイルと .yaml ファイルの両方を作成する必要があります
  2. 無効な YAML：yamllint と openapi-spec-validator で検証する必要があります
  3. 例の不足：「使用例」セクションは導入に不可欠です
  4. あいまいな検証：スキーマ検証は正確で、テスト可能である必要があります
  5. 累積タグの不足：レイヤー 9 には、上流のタグをすべて（7～8個）含める必要があります
  6. 必要な場合にスキップする：複数のチームで共有契約が必要な場合は、スキップしないでください
  7. 要素 ID の誤り：旧形式の INT-XXX、MODEL-XXX、CLAUSE-XXX ではなく、CTR.NN.xxxx を使用してください
  8. 累積タグコードの誤り：正しい要素タイプコードを使用してください（EARS=25、BDD=14、SYS=26、REQ=27、IMPL=29）

作成後の検証（必須 - 確認不要）

重要：ドキュメントを作成したら、直ちにこの検証ループを実行してください。検証に合格するまで、次のドキュメントに進まないでください。

自動検証ループ
LOOP:
  1. Run: python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed
検証コマンド
# Per-document validation (Phase 1)
python ai_dev_flow/scripts/validate_cross_document.py --document docs/CTR/CTR-NN_slug.md --auto-fix

# Layer validation (Phase 2) - run when all CTR documents complete
python ai_dev_flow/scripts/validate_cross_document.py --layer CTR --auto-fix
レイヤー固有の上流要件
このレイヤー必須の上流タグ数
CTR（レイヤー 8）@brd、@prd、@ears、@bdd、@adr、@sys、@req7タグ
自動修正アクション（確認不要）
問題修正アクション
上流タグの不足上流ドキュメントへの参照を付けて追加
タグ形式が無効TYPE.NN.xxxx（3セグメント）または TYPE-NN 形式に修正
リンク切れ現在の場所からパスを再計算
トレーサビリティセクションの不足テンプレートから挿入
検証コードの一覧
コード説明重大度
XDOC-001参照先の要件 ID が見つからないERROR
XDOC-002累積タグが不足しているERROR
XDOC-003上流ドキュメントが見つからないERROR
XDOC-006タグ形式が無効ERROR
XDOC-007累積タグの連鎖に欠落があるERROR
XDOC-009トレーサビリティセクションが不足しているERROR
品質ゲート

ブロッキング：はい - フェーズ 1 の検証がエラー 0 件で合格するまで、次のドキュメントに進めません。

次のスキル

CTR の作成後（またはこの任意のレイヤーをスキップした後）、次を使用してください。

doc-spec - 技術仕様を作成する（レイヤー 9）

SPEC では以下を行います。

  • 作成した場合は CTR を、作成していない場合は REQ を上流のソースとして参照します
  • 上流タグをすべて（7～8個）含めます
  • YAML 形式を使用します
  • 実装の詳細を定義します
  • 実装可能な状態を 100% 達成します

参考ドキュメント

CTR 成果物に関連する補足ドキュメントについて：

  • 形式：CTR-REF-NNN_{slug}.md
  • スキル：doc-ref スキルを使用
  • 検証：最小限（ブロッキングなし）
  • 例：API スタイルガイド、契約のバージョニングポリシー

関連リソース

  • テンプレート：ai_dev_ssd_flow/08_CTR/CTR-MVP-TEMPLATE.md（主たる基準）
  • スキーマテンプレート：ai_dev_ssd_flow/08_CTR/CTR-MVP-TEMPLATE.yaml（機械可読）
  • CTR 作成ルール：ai_dev_ssd_flow/08_CTR/CTR-MVP-TEMPLATE.md
  • CTR 検証ルール：ai_dev_ssd_flow/08_CTR/CTR_MVP_SCHEMA.yaml
  • CTR README：ai_dev_ssd_flow/08_CTR/README.md
  • OpenAPI 仕様：https://spec.openapis.org/oas/v3.0.3
  • JSON Schema：https://json-schema.org/
  • 共有標準：.claude/skills/doc-flow/SHARED_CONTENT.md
  • 命名標準：.claude/skills/doc-naming/SKILL.md（ID および命名規則）

セクションテンプレート（25K トークンを超えるドキュメント向け）：

  • インデックステンプレート：ai_dev_ssd_flow/08_CTR/CTR-SECTION-0-TEMPLATE.md
  • コンテンツテンプレート：ai_dev_ssd_flow/08_CTR/CTR-SECTION-TEMPLATE.md
  • 参考：ai_dev_flow/ID_NAMING_STANDARDS.md（セクション単位のファイル分割）

クイックリファレンス

CTR の目的：API コントラクトとデータスキーマを定義します

レイヤー：8（任意）

要素 ID の形式：CTR.NN.xxxx

  • インターフェース = 16
  • データモデル = 17
  • コントラクト条項 = 20

廃止されたパターン：INT-XXX、MODEL-XXX、CLAUSE-XXX、IF-XXX、DM-XXX、CC-XXX

ドキュメント管理フィールド：9 個必須

必須タグ：@brd から @req まで（7 個のタグ）

形式：2 ファイル（.md + .yaml）

SPEC 対応スコア：「Active」ステータスに必要なスコアは ≥90%

YAML 標準：

  • REST API には OpenAPI 3.0
  • データモデルには JSON Schema
  • イベント駆動型には AsyncAPI（該当する場合）

主なセクション：

  • コントラクトの概要
  • ビジネスコンテキスト（REQ のセクション 3 へのリンク）
  • YAML コントラクト定義
  • 使用例
  • 検証ルール
  • エラー処理

ディレクトリ構成：コントラクトが 30 件以上の場合はサブディレクトリを推奨します

任意：コントラクトがシンプルな場合、または REQ に埋め込まれている場合は、このレイヤーを省略します

次へ：doc-spec

バージョン履歴

バージョン日付変更内容作成者
1.22026-03-0612 個の品質ゲートを含む Pre-Commit Hooks サブセクションを追加。フックスクリプトの説明と YAML 設定を追加。バージョンメタデータを更新System
1.1.02026-02-08LAYER_REGISTRY v1.6 に基づき、レイヤー割り当てを 9 から 8 に更新。後続の成果物（SPEC レイヤー 9、TSPEC レイヤー 10、TASKS レイヤー 11）を更新。上流から IMPL を削除System
1.0.02025-01-15初期スキル定義System

コメント

Markdown 対応