geekfujiwara/codeappsdevelopmentstandard/spec-builder

仕様書作成スキル（一次情報 → 要件定義書）

office ドキュメント（PDF / PowerPoint / Excel / Word など）は anthropics/skills で読み取り、 画像ファイル（PNG/JPG 等）は agent-ocr で OCR する。

フォルダ構造

spec/                          ← スキル専用ディレクトリ
├── input/                     # 一次資料。クイックスタートではルートの業務資料を安全に移動・整理
├── output/                    # 全出力はここに入る（ユーザーが参照）
│   ├── staging/               # ファイル単位の中間 markdown
│   └── docs/                  # 統合要件定義書 5 点
│       ├── index.md           # ドキュメント一覧・開発利用フロー
│       ├── business-requirements.md
│       ├── functional-requirements.md
│       ├── design-requirements.md
│       └── test-requirements.md
└── .cache/                    # システム内部用（ユーザーは触らない）
    ├── conversion-checklist.json
    ├── pending_ocr.json
    └── pending_skills.json

最初の依頼を簡単にする

このスキルは 引数なしでも開始できる。

• 既定入力: spec/input/
• 既定 staging 出力: spec/output/staging/
• 既定 docs 出力: spec/output/docs/
• 既定 checklist: spec/.cache/conversion-checklist.json
• --input / --staging / --docs（互換: --output）/ --checklist を指定した場合はそのパスを優先する
• spec/input/ に変換対象が見つからない場合、scripts/convert_documents.py はワークスペース・フォルダ全体をスキャンし、変換候補になりうるファイルがないか確認する。候補が見つかった場合は一覧を提示するので、spec/input/ へ移動するか --input で対象パスを指定する
• 通常は元資料をその場所で読み、--input で指定する。クイックスタートの継続が承認された場合は、

下記の手順でルート直下の業務資料を spec/input/ へ整理する。その他の移動・削除は利用者の明示依頼が必要。

クイックスタートから呼ばれた場合

standard/references/quickstart.md の資料探索結果を引き継いで実行する。 .github に同梱された標準・サンプル、依存パッケージ、生成物、一時 clone、認証ファイルは業務資料ではない。 認証後の要望確認への継続回答を引き継ぎ、ルート直下の業務資料を spec/input/ へ移動・整理する。 エージェントが対象を選び、scripts/organize_input.py --workspace <workspace> --file "<document>" で計画し、 同じ引数に --apply を付けて実行する。複数ファイルは --file を繰り返す。 全件を事前検証し、同名ファイル・symlink・ルート外の指定・運用文書（README / AGENTS / LICENSE 等）を拒否する。 内容を照合してから元の場所のファイルを移し、失敗時は原本を保持してエラーを報告する。移動先・元の場所を記録する。 サブフォルダーの資料は元の場所を --input で参照してよい。原本の内容と承認済み仕様は保護する。 変換・統合後は architecture・テンプレート選定・開発環境へのフル構成デプロイ・実動作検証まで継続する。 業務資料から抽出した事実を推測で書き換えず、業界知識による補完は別の「仮説・推奨」として記録する。 資料なしなら空の変換結果で完了とせず、ワークスペース名から Step 0 で提案・選択された案を具体化し、 architecture の提案先行モードへ進む。白紙の業務ヒアリングは始めない。 既知事項や通常の実装判断で AskUserQuestion を繰り返さない。資料から分かることを自分で調べ、 本人の判断が不可欠な不足事項だけを確認する。

処理フロー

[spec/input/]
     │
     ├─ 画像 (PNG/JPG 等) ──→ spec/.cache/pending_ocr.json    ──→ agent-ocr
     │                                                                  │
     └─ 文書 (PDF/Office)  ──→ spec/.cache/pending_skills.json ──→ anthropics/skills
                                                                        │
                                                          ┌─────────────┘
                                                          ▼
                                              [spec/output/staging/]
                                                          │
                                                 (Claude が統合)
                                                          │
                                              [spec/output/docs/]
                                         ├── index.md
                                         ├── business-requirements.md
                                         ├── functional-requirements.md
                                         ├── design-requirements.md
                                         └── test-requirements.md

基本フロー

1. scripts/convert_documents.py で input 配下を走査する

• spec/input/ に変換対象がなければ、ワークスペース・フォルダ全体をスキャンして変換候補ファイルの有無を確認し、見つかった場合は一覧を提示する

1. 各ファイルの staging ファイルを spec/output/staging/ に作成する

• ファイル名は 元のファイル名.元の拡張子.MD（例: 要件定義.docx.MD）

1. 画像ファイルは spec/.cache/pending_ocr.json に記録し、agent-ocr で後続処理する
2. 画像以外の文書は spec/.cache/pending_skills.json に記録し、anthropics/skills で後続処理する
3. spec/output/docs/ に以下 5 つを作成する

• index.md（ドキュメント一覧・開発利用フロー）
• business-requirements.md
• functional-requirements.md
• design-requirements.md
• test-requirements.md

1. spec/.cache/conversion-checklist.json を更新する

• 新規ファイルはチェックリストへ追加
• is_completed=false または更新差分ありのファイルのみ再処理
• 全件完了時は既存 spec/output/docs/ を参照して開発を継続

staging → docs 統合フロー

staging の変換完了後、以下の手順で docs を更新する。

1. spec/.cache/conversion-checklist.json を読み、is_completed=false のファイルがないか確認する
2. is_completed=false が残っていれば、対象の staging ファイルを読んで内容を補完する
3. 全 staging ファイルを横断し、各 docs の 要確認 を実際の要件に書き換える：

• business-requirements.md → ステークホルダー・ユーザーストーリー・業務フロー
• functional-requirements.md → 機能一覧(MoSCoW)・データモデル・非機能要件
• design-requirements.md → 全体構成・コンポーネント・リスク・実装タスク分解（★全体構成・コンポーネント選定は architecture スキル の判断を正として転記する）
• test-requirements.md → テストシナリオ・受け入れ条件（functional の機能一覧 # と対応。条件本文の正は functional 側）

1. index.md の処理状況テーブルも合わせて更新する
2. 推測で埋めず、情報不足は 要確認 として残す

agent-ocr 更新方針

画像の出力先とファイル名は新構成に合わせる。

• 出力先: spec/output/staging/
• ファイル名: 元のファイル名.元の拡張子.MD
• OCR 抽出時は表を markdown table 化し、判読不能箇所は [判読不可] と明記する

pending_ocr.json の staging_markdown_path を使って、対象ファイルを更新する。 pending_ocr.json の ocr_prompt_hint を agent-ocr の抽出指示として利用する。

anthropics/skills 更新方針

画像以外の文書は pending_skills.json を使って処理する。

• source_path の元ファイルを anthropics/skills で読み取り
• context_hint を参照してどの観点で内容を抽出するかを確認する
• 抽出 markdown を staging_markdown_path に反映
• 処理済み後、docs の 5 文書を更新

補足: anthropics/skills（Claude）は画像読解も可能だが、このスキルでは OCR の責務を agent-ocr に固定する。

spec/output/docs/ で整理する観点

index.md

• ドキュメント一覧（各 docs へのリンクと役割）
• 処理状況テーブル
• 開発利用フロー（番号付き手順）

business-requirements.md

• 概要（対象業務・プロジェクト背景・スコープ）
• ステークホルダー / ロール（ロール・担当業務・関心事の表）
• ユーザーストーリー（As a…I want…so that…形式）
• 業務フロー
• 未確定事項 / 要確認事項（項目・確認先・期限・ステータスの表）
• 要件変更履歴（変更理由を必ず併記）

functional-requirements.md

• 機能一覧（MoSCoW 優先度・受け入れ条件の表 — 受け入れ条件の正はここ）
• Dataverse テーブル候補（テーブル名・主な列・リレーション）
• UI 要件（Code Apps / Model-Driven Apps / Cowork プラグイン — 選定の確定は architecture スキル を優先）
• Power Automate の自動化要件
• Copilot Studio / AI Builder の利用余地（採用可否・v1/v2 判断は architecture スキルに従う）
• 外部連携
• 非機能要件（パフォーマンス・セキュリティ・可用性・スケーラビリティ・ユーザビリティ — test-requirements の非機能テストと区分を一致させる）
• 要件変更履歴（変更理由を必ず併記）

design-requirements.md

★ 全体構成・コンポーネント選定・構築フェーズは architecture スキル を正とする。

本ドキュメントには architecture スキルの判断フロー・設計アウトプットテンプレートで確定した結果を転記する。

• Power Platform 全体構成案（architecture スキルのテンプレート準拠、Mermaid 構成図）
• コンポーネント設計（種別・役割・依存の表 — architecture スキルの「コンポーネント構成」表と整合させる）
• セキュリティ / 権限 / 監査（区分・内容・対応方針の表）
• 設計上のリスク（リスク・影響度・発生確率・対応方針の表）
• Phase 1 確認事項
• 実装タスク分解（タスク・依存・優先度・見積の表 — フェーズ順序は architecture スキルの「構築フェーズ」に沿う）
• 要件変更履歴（変更理由を必ず併記）

test-requirements.md

• テスト戦略（テスト方針・環境・自動化範囲）
• テストシナリオ（シナリオ名・前提条件・操作手順・期待結果・優先度の表）
• 受け入れ条件（functional-requirements の機能 # を参照し確認方法を定義 — 条件本文の正は functional 側、二重管理しない）
• 非機能テスト（区分・テスト内容・合格基準の表 — 区分は functional の非機能要件と一致させる）
• 要件変更履歴（変更理由を必ず併記）

実行例

cd .github/skills/spec-builder/scripts
python convert_documents.py

参照

• 変換ガイド
• architecture スキル — 全体構成・コンポーネント選定の正（design-requirements / UI・AI 連携要件はこちらを優先して参照）