doc-sys

Name: doc-sys
Author: vladm3105

github.com/vladm3105ドキュメント1741 回インストール1 日前に更新

リポジトリ

doc-sys について

SDD ワークフローで第6層のシステム要件（SYS）文書を作成するスキルです。上流の要件とアーキテクチャ決定を構造化し、トレーサビリティと検証の指針を示します。

主な機能

01SYS 文書の構成ガイド
02上流成果物と ADR の確認
03累積的なトレーサビリティタグ
04要件 ID と閾値参照
05検証と品質ゲートの指針

活用シーン

01BRD から ADR まで完了後の SYS 文書作成
02REQ 分解前の SYS 準備状況の確認

インストール

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

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

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

詳細

doc-sys

目的

**システム要件（SYS）**ドキュメントを作成します。SDD ワークフローのレイヤー 6 の成果物であり、機能要件や品質特性を含む技術的なシステム要件を定義します。

レイヤー：6

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

下流の成果物：REQ（レイヤー 7）、コード（レイヤー 13）

前提条件

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

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

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

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

トレーサビリティタグでは、既存のドキュメントのみを参照します
上流成果物の種類が実際に存在しない場合に限り、nullを使用します
BRD-XXXやTBDなどのプレースホルダーは絶対に使用しないでください
不足している上流成果物は作成しないでください。機能はスキップします

SYS を作成する前に、次を確認してください。

共有標準：.claude/skills/doc-flow/SHARED_CONTENT.md
上流の ADR：システムを制約するアーキテクチャ上の決定事項を確認します
テンプレート：ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md
作成ルール：ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md
検証ルール：ai_dev_ssd_flow/06_SYS/SYS_MVP_SCHEMA.yaml
品質ゲート検証：ai_dev_ssd_flow/06_SYS/SYS_MVP_QUALITY_GATE_VALIDATION.md

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

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

BRD から ADR まで（レイヤー 1～5）が完了している
システムレベルの技術要件を定義する必要がある
アーキテクチャ上の決定事項を要件に変換する
機能的なシステム動作と品質特性を指定する
SDD ワークフローのレイヤー 6 に進んでいる

予約 ID の適用除外（SYS-00_*）

適用範囲：予約 ID 000を持つドキュメントは、検証の対象から完全に除外されます。

パターン：SYS-00_*.md

ドキュメントの種類：インデックス、トレーサビリティマトリクス、用語集、レジストリ、チェックリスト

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

SYS 固有のガイダンス

1. SYS MVP の構成（全 15 セクション）

MVP テンプレート：全 15 セクションの構成については、ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.mdを参照してください。

パート 1 - システムの定義：

ドキュメント管理、エグゼクティブサマリー、スコープ

パート 2 - システム要件：

機能要件、品質特性

パート 3 - システム仕様：

インターフェース仕様、データ管理要件、テストおよび検証要件

パート 4 - システム運用：

デプロイおよび運用要件、コンプライアンスおよび規制要件

パート 5 - 検証および管理：

受け入れ基準、リスク評価、トレーサビリティ、実装上の注意事項

2. ドキュメント管理の要件

必須フィールド（必須 9 項目）：

ステータス、バージョン、作成日／最終更新日、作成者、レビュー担当者、オーナー、優先度
EARS 対応スコア
REQ 対応スコア

形式：

| Item | Details |
|------|---------|
| **EARS-Ready Score** | ✅ 95% (Target: ≥90%) |
| **REQ-Ready Score** | ✅ 95% (Target: ≥90%) |

3. REQ 対応スコアリングシステム

目的：SYS の成熟度と、要件（REQ）への分解に進む準備状況を測定します。

形式：✅ NN% (Target: ≥90%)

ステータスと REQ 対応スコアの対応関係：

REQ 対応スコア	必須ステータス
≥90%	承認済み
70-89%	レビュー中
<70%	ドラフト

スコアリング基準：

要件分解の明確さ（35%）：システム境界、機能分解、依存関係、ADR との整合性
品質特性の定量化（30%）：パフォーマンスのパーセンタイル、信頼性 SLA、セキュリティコンプライアンス、スケーラビリティ指標
インターフェース仕様（20%）：外部 API（CTR 対応）、内部インターフェース、データ交換プロトコル
実装準備状況（15%）：テスト要件、デプロイ／運用、モニタリング／可観測性

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

4. 要素 ID の形式（必須）

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

要素タイプ	コード	例
機能要件	01	SYS.02.0101
品質属性	02	SYS.02.0201
ユースケース	11	SYS.02.1101
システム要件	26	SYS.02.2601

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

❌ FR-XXX → SYS.NN.01.SS を使用
❌ QA-XXX → SYS.NN.02.SS を使用
❌ UC-XXX → SYS.NN.11.SS を使用
❌ SR-XXX → SYS.NN.26.SS を使用

参照：ID_NAMING_STANDARDS.md

5. システムコンポーネントの分類

システムの種類：

API サービス：REST、GraphQL、その他の API インターフェース
データ処理：ETL、ストリーム処理、バッチ処理システム
統合サービス：アダプター、コネクター、プロキシサービス
支援サービス：キャッシュ、メッセージング、構成サービス
インフラストラクチャコンポーネント：ロードバランサー、ゲートウェイ、監視システム

重要度レベル：

ミッションクリティカル：ダウンタイム SLA が 1 時間未満の、収益を生み出すシステム
ビジネスクリティカル：ダウンタイム SLA が 4 時間未満の、主要な業務システム
運用支援：ダウンタイム SLA が 24 時間未満の、バックオフィスシステム

6. 閾値レジストリとの統合

目的：一元管理された閾値レジストリを参照し、マジックナンバーを防止します。

@threshold タグの形式：

@threshold: PRD.NN.category.subcategory.key

SYS 固有の閾値カテゴリ：

カテゴリ	SYS での用途	キーの例
`perf.*`	パフォーマンス要件	`perf.api.p95_latency`
`sla.*`	稼働時間と可用性の目標	`sla.uptime.target`
`timeout.*`	サーキットブレーカー、接続タイムアウト	`timeout.circuit_breaker.threshold`
`resource.*`	メモリ、CPU、ストレージの上限	`resource.memory.max_heap`
`limit.*`	レート制限、接続数の制限	`limit.connection.max_total`

無効（値のハードコード）：

❌ p95 latency: 200ms
❌ uptime: 99.9%

有効（レジストリ参照）：

✅ p95 latency: @threshold: PRD.NN.perf.api.p95_latency
✅ uptime: @threshold: PRD.NN.sla.uptime.target

タグ形式の規約（設計によるもの）

表記	形式	成果物	目的
ハイフン	TYPE-NN	ADR、SPEC、CTR	技術成果物 - ファイル／ドキュメントへの参照
ドット	TYPE.NN.xxxx	BRD、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 を指します

累積タグ付けの要件

レイヤー 6（SYS）：レイヤー 1〜5（BRD、PRD、EARS、BDD、ADR）のタグを含める必要があります

タグ数：5 個のタグ（@brd、@prd、@ears、@bdd、@adr）

形式：

## Traceability

**Required Tags** (Cumulative Tagging Hierarchy - Layer 6):

@brd: BRD.01.0103
@prd: PRD.01.0702, PRD.01.0715
@ears: EARS.01.2501, EARS.01.2502
@bdd: BDD.01.1401
@adr: ADR-033, ADR-045

上流のソース：

BRD-01
PRD-01
EARS-01 - EARS タイプコード：25
BDD-01 - BDD シナリオタイプコード：14
ADR-033

上流／下流の成果物

上流ソース:

BRD（レイヤー 1）- ビジネス要件
PRD（レイヤー 2）- 製品機能
EARS（レイヤー 3）- 形式的な要件
BDD（レイヤー 4）- テストシナリオ
ADR（レイヤー 5）- アーキテクチャ上の決定事項（重要 - 制約を定義します）

下流の成果物:

REQ（レイヤー 7）- SYS から分解されたアトミックな要件
Code（レイヤー 13）- システム要件の実装

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

@related-sys: SYS-NN - システムコンテキストを共有する SYS ドキュメント
@depends-sys: SYS-NN - 先に実装する必要がある SYS

作成プロセス

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

特に ADR（レイヤー 5）に注目してください。アーキテクチャ上の決定事項はシステム要件を制約します。

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

docs/06_SYS/ を確認し、次に使用可能な ID 番号を確認します。

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

✅ 正しい: SYS-01、SYS-99、SYS-102
❌ 誤り: SYS-001、SYS-009（余分な先行ゼロは不要です）

ステップ 3: SYS ファイルを作成する

入れ子フォルダーの規則（必須）: ドキュメントのサイズに関係なく、すべての SYS ドキュメントで入れ子フォルダーを使用する必要があります。

場所: docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md

例: docs/06_SYS/SYS-01_order_management/SYS-01_order_management.md

重要: 入れ子フォルダー構造を使わずに、docs/06_SYS/ 直下に SYS ファイルを作成しないでください。

ステップ 4: ドキュメント管理セクションに記入する

EARS-Ready Score と REQ-Ready Score を含むメタデータを完成させます。

ステップ 5: システム要件を定義する

各要件について:

統一された要素 ID 形式（SYS.NN.xxxx）を使用します
入力、処理、出力を指定します（機能要件の場合）
測定可能な基準を指定します（品質特性の場合）
すべての定量値に @threshold タグを使用します
上流の EARS／PRD を参照します
BDD 検証にリンクします

ステップ 6: システムフローを作成する

テキストベースではなく Mermaid 図を使用します:

インタラクションにはシーケンス図
ロジックにはフローチャート
ワークフローには状態遷移図

ステップ 7: 技術的制約を記録する

ADR の決定事項に基づいて:

各制約を列挙します
影響を説明します
検証方法を定義します

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

上流のタグを 5 つすべて（@brd、@prd、@ears、@bdd、@adr）含めます。

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

必須: トレーサビリティマトリクス（docs/06_SYS/SYS-00_TRACEABILITY_MATRIX.md）を更新します。

ステップ 10: SYS を検証する

検証コマンドを実行します（「検証」セクションを参照）。

ステップ 11: 変更をコミットする

SYS ファイルとトレーサビリティマトリクスをコミットします。

検証

検証チェック（全 8 項目）

チェック	種別	説明
CHECK 1	エラー	必須のドキュメント管理フィールド（9 項目）
CHECK 2	エラー	ADR 準拠の検証
CHECK 3	エラー	REQ-Ready Score の検証（形式、しきい値）
CHECK 4	エラー	品質特性の定量化
CHECK 5	警告	システム境界
CHECK 6	警告	インターフェース仕様（CTR 対応）
CHECK 7	警告	上流のトレーサビリティ
CHECK 8	エラー	要素 ID 形式の準拠（統一された 3 セグメント形式）

検証レベル

レベル	種別	終了コード	アクション
Tier 1	エラー	1	コミット前に修正が必要です
Tier 2	警告	0	修正を推奨します
Tier 3	情報	0	対応不要です

コミット前フック

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

- id: sys-core-validator
  name: Validate SYS core checks (validator, framework library)
  entry: bash ai_dev_ssd_flow/06_SYS/scripts/sys_core_validator_hook.sh
  stages: [pre-commit]

- id: sys-quality-gate
  name: Validate SYS quality gates
  entry: bash ai_dev_ssd_flow/06_SYS/scripts/sys_quality_gate_hook.sh
  stages: [pre-commit]

- id: sys-req-ready-score
  name: Validate SYS REQ-Ready score (≥90%)
  entry: bash ai_dev_ssd_flow/06_SYS/scripts/sys_req_ready_score_hook.sh
  stages: [pre-commit]

手動実行（コミットせずにテストする場合）:

pre-commit run sys-core-validator --all-files
pre-commit run sys-quality-gate --all-files
pre-commit run sys-req-ready-score --all-files

適用される品質ゲート:

✅ SYS 構造への準拠（MVP の 15 セクション）
✅ Approved ステータスに必要な REQ-Ready Score ≥90%
✅ メタデータとタグ（sys、layer-6-artifact）
✅ 上流のトレーサビリティ（@brd、@prd、@ears、@bdd、@adr）
✅ 要素 ID 形式（SYS.NN.xxxx）
✅ Approved ドキュメントにプレースホルダーテキストがないこと
✅ システム図（Mermaid が必須）
✅ @threshold タグを使用した測定可能な要件
✅ 機能要件と品質特性の網羅性

自動検証

# Per-document validation (Phase 1)
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md --verbose

# Layer validation (Phase 2) - run when all SYS documents complete
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/ --verbose

# Cumulative tagging validation
python ai_dev_ssd_flow/scripts/validate_tags_against_docs.py --artifact SYS-01 --expected-layers brd,prd,ears,bdd,adr --strict

手動チェックリスト

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

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

自動検証ループ

LOOP:
  1. Run: python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py {doc_path} --verbose
  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

レイヤーごとの上流要件

このレイヤー	必須の上流タグ	数
SYS（レイヤー 6）	@brd、@prd、@ears、@bdd、@adr	5 タグ

自動修正アクション（確認不要）

問題	修正アクション
@brd/@prd/@ears/@bdd/@adr タグがない	上流ドキュメントへの参照を付けて追加
タグ形式が無効	TYPE.NN.xxxx（3セグメント）または TYPE-NN 形式に修正
レガシー要素 ID（FR-XXX、QA-XXX など）	SYS.NN.xxxx 形式に変換
リンク切れ	現在の場所からパスを再計算
トレーサビリティセクションがない	テンプレートから挿入

検証コードの一覧

コード	説明	重大度
XDOC-001	参照先の要件 ID が見つからない	エラー
XDOC-002	累積タグがない	エラー
XDOC-003	上流ドキュメントが見つからない	エラー
XDOC-006	タグ形式が無効	エラー
XDOC-007	累積タグチェーンに欠落がある	エラー
XDOC-009	トレーサビリティセクションがない	エラー

品質ゲート

ブロック条件：はい - フェーズ 1 の検証でエラーが 0 件になるまで、REQ の作成に進めません。

よくある落とし穴

曖昧な要件：測定可能である必要があります（「高速」ではなく「P95 <50ms」）
ADR 制約の欠落：システム要件は ADR の決定に従う必要があります
テキストベースの図：ASCII アートやコードブロックではなく、Mermaid のみを使用してください
累積タグの欠落：レイヤー 6 には、上流のタグを 5 つすべて含める必要があります
検証方法がない：各要件にテスト方法が必要です
レガシー要素 ID：FR-XXX/QA-XXX/SR-XXX ではなく SYS.NN.xxxx を使用してください
値のハードコード：マジックナンバーではなく、@threshold タグを使用してください
REQ-Ready Score の形式が誤っている：✅ 絵文字とパーセンテージを含める必要があります

下流ドキュメント作成ガイドライン

SYS から REQ を作成する

REQ の分解ルール：

SYS の機能要件ごとに、3～7 個のアトミック REQ ファイルを作成
SYS の品質属性カテゴリごとに、カテゴリあたり 2～4 個のアトミック REQ ファイルを作成
SYS のインターフェースごとに、インターフェースあたり 1～3 個のアトミック REQ ファイルを作成

SYS に対する REQ の検証：

すべての REQ の機能は SYS のシステム境界内に収まる必要があります
すべての REQ の受け入れ基準は SYS の終了基準を満たす必要があります
すべての REQ の品質属性目標は SYS のしきい値以上である必要があります

インターフェース CTR の作成：

SYS で外部 API 契約を指定している場合は、CTR ドキュメントを作成します
CTR の要件は SYS のインターフェース仕様と正確に一致する必要があります

次のスキル

SYS の作成後、次を使用します：

doc-req - アトミック要件を作成（レイヤー 7）

REQ では次を行います：

SYS をアトミック要件に分解
上流タグを 6 つすべて（@brd から @sys まで）含める
REQ v3.0 形式（12 セクション）を使用
SPEC-readiness を 90% 以上にする

参考ドキュメント

SYS アーティファクトでは REF ドキュメントはサポートされていません。SDD フレームワークでは、参考ドキュメントは BRD と ADR のタイプのみに限定されています。

補足ドキュメントが必要な場合は、次を作成してください：

BRD-REF：ビジネスコンテキストのドキュメント
ADR-REF：システムアーキテクチャガイド、QA 属性カタログ

クイックリファレンス

SYS の目的：システムレベルの技術要件を定義します

レイヤー：6

必須タグ：@brd、@prd、@ears、@bdd、@adr（5 個のタグ）

REQ 対応スコア：「承認済み」ステータスに必要な値は 90% 以上です

要素 ID 形式：SYS.NN.xxxx（FR=01、QA=02、UC=11、SR=26）

主なセクション：

システム要件（統一された要素 ID）
システムフロー（Mermaid 図）
技術的制約（ADR に基づく）

重要：すべての定量値に @threshold タグを使用してください

次のドキュメント：doc-req

バージョン履歴

バージョン	日付	変更内容	作成者
1.2	2026-03-06	品質ゲート検証の参照と pre-commit フックのセクションを追加	System
1.1	2026-02-27	frontmatter を `metadata` に移行し、SYS の正規参照先を `ai_dev_ssd_flow` に統一。存在しないセクションテンプレートへの参照を削除し、検証コマンドを `validate_sys.py` に統一	System
1.0	2026-02-08	YAML frontmatter 標準化を含むスキル定義の初版	System

Markdown 対応

ログインしてコメント

基本情報

作者: vladm3105
リポジトリ: vladm3105/aidoc-flow-framework
カテゴリ: ドキュメント
インストール数: 41
GitHub スター: 17

問題を報告

doc-sys

doc-sys について

主な機能

活用シーン

インストール

詳細

doc-sys

目的

前提条件

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

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

予約 ID の適用除外（SYS-00_*）

SYS 固有のガイダンス

1. SYS MVP の構成（全 15 セクション）

2. ドキュメント管理の要件

3. REQ 対応スコアリングシステム

4. 要素 ID の形式（必須）

5. システムコンポーネントの分類

6. 閾値レジストリとの統合

タグ形式の規約（設計によるもの）

累積タグ付けの要件

上流／下流の成果物

作成プロセス

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

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

ステップ 3: SYS ファイルを作成する

ステップ 4: ドキュメント管理セクションに記入する

ステップ 5: システム要件を定義する

ステップ 6: システムフローを作成する

ステップ 7: 技術的制約を記録する

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

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

ステップ 10: SYS を検証する

ステップ 11: 変更をコミットする

検証

検証チェック（全 8 項目）

検証レベル

コミット前フック

自動検証

手動チェックリスト

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

自動検証ループ

レイヤーごとの上流要件

自動修正アクション（確認不要）

検証コードの一覧

品質ゲート

よくある落とし穴

下流ドキュメント作成ガイドライン

SYS から REQ を作成する

次のスキル

参考ドキュメント

関連リソース

クイックリファレンス

バージョン履歴

コメント