context-analyzer

context-analyzer

目的

プロジェクト構造をスキャンし、インテリジェントなドキュメント作成のためのコンテキストモデルを構築します。

解決する問題：ドキュメントを作成する際、AI アシスタントはプロジェクトのコンテキスト、既存の成果物、現在のワークフローの状態を把握できないため、参照の抜けやコンテンツの重複が発生します。

解決策：プロジェクトのディレクトリを分析し、成果物のメタデータとトレーサビリティのセクションを解析して、新しいドキュメントの作成に役立つ情報を提示するコンテキストモデルを構築します。

このスキルを使用する場面

context-analyzer を使用する場合：

• 既存のプロジェクトでドキュメント作業を始めるとき
• 上流の参照が必要な新しい成果物を作成するとき
• 既存のドキュメントを把握する必要があるとき
• ドキュメントの網羅性における不足を特定したいとき
• doc-* スキルを呼び出すためのコンテキストを準備するとき

次の場合は使用しないでください：

• プロジェクトに既存のドキュメントがない場合
• 単独のドキュメントに取り組んでいる場合
• プロジェクト全体の監査が必要な場合（代わりに trace-check を使用してください）

スキルの入力

入力	型	必須	説明
project_root	string	はい	分析対象プロジェクトのルートパス
target_artifact_type	string	いいえ	作成する成果物の種類（例：「PRD」、「SPEC」）
depth	string	いいえ	分析の深さ：「quick」（構造のみ）、「standard」（デフォルト）、「deep」（コンテンツ全体）

スキルのワークフロー

ステップ 1：プロジェクト構造をスキャンする

種類と場所ごとに、すべてのドキュメント成果物を列挙します。

ディレクトリのパターン：

{project_root}/
├── docs/
│   ├── BRD/
│   ├── PRD/
│   ├── EARS/
│   ├── BDD/
│   ├── ADR/
│   ├── SYS/
│   ├── REQ/
│   ├── IMPL/
│   ├── CTR/
│   ├── SPEC/
│   └── TASKS/
└── ai_dev_flow/  (framework templates)

成果物の検出：

# Example discovery pattern
find {project_root}/docs -name "*.md" -o -name "*.yaml" -o -name "*.feature"

出力構造：

artifact_inventory:
  BRD:
    count: 3
    files:
      - id: BRD-01
        path: docs/BRD/BRD-01_platform_foundation.md
        title: Platform Foundation
        status: Approved
      - id: BRD-02
        path: docs/BRD/BRD-02_partner_integration.md
        title: Partner Integration
        status: Draft
  PRD:
    count: 2
    files:
      - id: PRD-01
        path: docs/PRD/PRD-01_core_features.md
        title: Core Features
        status: In Review
  SPEC:
    count: 0
    files: []

ステップ 2：成果物のメタデータを解析する

検出した成果物からメタデータと重要な情報を抽出します。

YAML フロントマターの抽出：

# From document header
---
title: "BRD-01: Platform Foundation"
tags:
  - platform-brd
  - shared-architecture
custom_fields:
  layer: 1
  artifact_type: BRD
  status: Approved
---

ドキュメント管理情報の抽出：

## Document Control

| Item | Details |
|------|---------|
| **Status** | Approved |
| **Version** | 2.1.0 |
| **Last Updated** | 2025-11-15 |

解析済みメタデータモデル：

artifact_metadata:
  BRD-01:
    title: Platform Foundation
    layer: 1
    status: Approved
    version: 2.1.0
    last_updated: 2025-11-15
    tags: [platform-brd, shared-architecture]

ステップ 3：トレーサビリティ情報を抽出する

各成果物からセクション 7 のトレーサビリティを解析します。

上流ソースの抽出：

### Upstream Sources
| Source | Type | Reference |
|--------|------|-----------|
| [BRD-01](../BRD/BRD-01_platform.md#BRD-01) | Business Requirements | Platform foundation |

下流の成果物の抽出：

### Downstream Artifacts
| Artifact | Type | Reference |
|----------|------|-----------|
| [SPEC-01](../SPEC/SPEC-01_api.yaml) | Technical Specification | API implementation |

トレーサビリティグラフ：

traceability_graph:
  BRD-01:
    upstream: []
    downstream: [PRD-01, PRD-00]
  PRD-01:
    upstream: [BRD-01]
    downstream: [EARS-01, SPEC-01]
  SPEC-01:
    upstream: [PRD-01, REQ-01]
    downstream: [TASKS-01]

ステップ 4：ワークフロー上の位置を特定する

SDD ワークフローにおける現在の位置を算出します。

レイヤーの対応関係：

レイヤー	成果物の種類	必須の上流成果物
1	BRD	なし
2	PRD	BRD
3	EARS	PRD
4	BDD	EARS
5	ADR	BDD
6	SYS	ADR
7	REQ	SYS
8	IMPL	REQ（任意）
9	CTR	IMPL または REQ（任意）
10	SPEC	REQ、IMPL/CTR は任意
11	TASKS	SPEC

位置の分析：

workflow_position:
  completed_layers: [1, 2, 3]
  current_layer: 4
  next_required: [BDD, ADR]
  gaps:
    - layer: 3
      type: EARS
      status: incomplete
      reason: "Only 2 of 5 PRD features have EARS coverage"

ステップ 5：上流候補を特定する

対象の成果物の種類に関連する上流ドキュメントを特定します。

関連性のスコアリング：

要素	重み	説明
直接の上流成果物	50%	ワークフローにおける直前の成果物
トピックの一致	30%	キーワードとドメインの適合度
新しさ	10%	最近更新されたドキュメント
ステータス	10%	承認済みのドキュメントを優先

上流候補の出力：

upstream_candidates:
  target_type: SPEC
  candidates:
    - id: REQ-01
      relevance: 95%
      title: API Requirements
      reason: "Direct upstream, topic match: API, approved status"
    - id: REQ-02
      relevance: 80%
      title: Data Model Requirements
      reason: "Direct upstream, related topic: data"
    - id: ADR-005
      relevance: 70%
      title: API Architecture Decision
      reason: "Architecture context for API design"

ステップ 6：重要な用語を抽出する

既存のドキュメントからプロジェクトの用語集を作成します。

用語の抽出方法：

• ドキュメントのタイトルと見出し
• 用語集のセクション
• 頻繁に使用される技術用語
• ドメイン固有の用語

重要な用語の出力：

key_terms:
  domain_terms:
    - term: workflow
      frequency: 45
      documents: [BRD-01, PRD-01, REQ-01]
    - term: resource
      frequency: 32
      documents: [BRD-01, REQ-02, SPEC-01]
  technical_terms:
    - term: WebSocket
      frequency: 18
      documents: [ADR-003, SPEC-01]
    - term: PostgreSQL
      frequency: 12
      documents: [BRD-01, ADR-000]

ステップ 7：コンテキストモデルを構築する

セッションで使用する包括的なコンテキストモデルをまとめます。

完全なコンテキストモデル：

context_model:
  project_root: /path/to/project
  scan_timestamp: 2025-11-29T14:30:00Z
  scan_depth: standard

  artifact_inventory:
    total_count: 25
    by_type:
      BRD: 3
      PRD: 5
      EARS: 4
      BDD: 6
      ADR: 3
      REQ: 4
      SPEC: 0
      TASKS: 0

  workflow_position:
    completed_layers: [1, 2, 3, 4, 5, 7]
    current_layer: 7
    ready_for: [SPEC, TASKS]
    gaps:
      - type: SYS
        status: missing
        impact: "SPEC creation may lack system context"

  upstream_candidates:
    target_type: SPEC
    primary:
      - id: REQ-01
        title: Core API Requirements
        relevance: 95%
    secondary:
      - id: ADR-003
        title: WebSocket Architecture
        relevance: 75%

  key_terms:
    domain: [workflow, resource, validation, processing]
    technical: [WebSocket, PostgreSQL, Redis, REST API]

  coverage_gaps:
    - area: Testing
      description: "BDD scenarios cover only 60% of EARS requirements"
    - area: Implementation
      description: "No SPEC or TASKS documents created yet"

使用例

例 1：SPEC 作成前のコンテキスト

ユーザーのリクエスト：「これから SPEC ドキュメントを作成します。どのようなコンテキストがありますか？」

コンテキスト分析：

context_summary:
  target: SPEC creation
  readiness: ready
  upstream_available:
    - REQ-01: Core API Requirements (Approved)
    - REQ-02: Data Model Requirements (Approved)
    - ADR-003: WebSocket Architecture (Approved)
  recommended_references:
    - "Reference REQ-01 for API endpoint specifications"
    - "Include ADR-003 for WebSocket implementation decisions"
  warnings:
    - "No CTR (contract) documents exist - consider if API contracts needed"

例 2：不足の分析

ユーザーのリクエスト：「このプロジェクトで不足しているドキュメントは何ですか？」

不足の分析結果：

documentation_gaps:
  critical:
    - type: SYS
      reason: "No system requirements linking ADR to REQ"
      impact: "REQ documents may lack architectural context"
    - type: SPEC
      reason: "No technical specifications for implementation"
      impact: "Cannot proceed to code generation"
  moderate:
    - type: BDD
      coverage: 60%
      reason: "4 of 10 EARS requirements have BDD scenarios"
  low:
    - type: IMPL
      reason: "Implementation plan optional but recommended for complex projects"

例 3：構造のクイックチェック

ユーザーのリクエスト：「このプロジェクトにはどのようなドキュメントがありますか？」

クイックスキャンの出力（深さ：quick）：

project_structure:
  docs_directory: /project/docs
  artifact_counts:
    BRD: 3
    PRD: 5
    EARS: 4
    BDD: 6
    ADR: 3
    SYS: 0
    REQ: 4
    IMPL: 0
    CTR: 0
    SPEC: 0
    TASKS: 0
  total_artifacts: 25
  workflow_coverage: 50% (6 of 12 layers)

他のスキルとの連携

連携	説明
skill-recommender	より適切な推奨のためにプロジェクトのコンテキストを提供します
doc-* skills	上流候補と重要な用語を提供します
quality-advisor	検証用の成果物一覧を共有します
workflow-optimizer	ワークフロー内の位置データを提供します
trace-check	トレーサビリティの抽出と重複します（詳細な検証には trace-check を使用します）

品質ゲート

完了の定義

• プロジェクト構造のスキャンに成功している
• すべての成果物の種類が検出されている
• 検出された成果物からメタデータが抽出されている
• トレーサビリティグラフが構築されている
• ワークフロー内の位置が算出されている
• 対象の種類に対する上流候補が特定されている
• コンテキストモデルが組み立てられ、返されている

パフォーマンス目標

指標	目標
クイックスキャンの遅延	<500ms
標準スキャンの遅延	100 個の成果物で <2s
詳細スキャンの遅延	100 個の成果物で <5s
メモリ使用量	100 個の成果物で <200MB

トレーサビリティ

必須タグ：

@prd: PRD.000.002
@adr: ADR-000

上流ソース

ソース	種類	参照
PRD-00	製品要件	PRD-00
ADR-000	アーキテクチャ決定	ADR-000

下流成果物

成果物	種類	参照
skill-recommender	スキル利用者	より適切な推奨のためにコンテキストを使用します
doc-* skills	スキル利用者	成果物の作成にコンテキストを使用します

---

バージョン情報

バージョン: 1.0.0 作成日: 2025-11-29 ステータス: Active 作成者: AI Dev Flow Framework Team