specdojo 0.8.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/agents/specdojo-orchestrator.md +4 -1
- package/CHANGELOG.md +64 -0
- package/dist/catalog/catalog.js +16 -14
- package/dist/commands/agent.js +5 -3
- package/dist/commands/build.js +69 -10
- package/dist/commands/git.js +206 -0
- package/dist/commands/init.js +4 -2
- package/dist/commands/where.js +25 -0
- package/dist/dashboard/dashboard.js +5 -3
- package/dist/dashboard/routines.js +4 -7
- package/dist/dashboard/timeline.js +14 -14
- package/dist/docs/index-command.js +2 -2
- package/dist/docs/yaml-business-tables.js +243 -0
- package/dist/docs/yaml-interface-tables.js +106 -0
- package/dist/docs/yaml-pages-command.js +5 -3
- package/dist/docs/yaml-pages.js +146 -3
- package/dist/docs/yaml-table-shared.js +70 -0
- package/dist/docs/yaml-tables.js +39 -0
- package/dist/exec/agent-config.js +9 -0
- package/dist/exec/agent-protected-config.js +2 -0
- package/dist/exec/commands.js +31 -18
- package/dist/exec/events.js +34 -14
- package/dist/exec/evidence.js +13 -3
- package/dist/exec/parent-validation.js +56 -3
- package/dist/exec/plans-core.js +21 -2
- package/dist/exec/plans-generation.js +6 -7
- package/dist/exec/post-integration.js +162 -0
- package/dist/exec/queue-command.js +166 -0
- package/dist/exec/queue.js +285 -0
- package/dist/exec/register-foreign-wait.js +84 -0
- package/dist/exec/repo-integration-sync.js +17 -5
- package/dist/exec/reporter.js +2 -2
- package/dist/exec/results.js +24 -4
- package/dist/exec/review-kata.js +4 -1
- package/dist/exec/run/agent-pipeline.js +3 -2
- package/dist/exec/run/agent.js +12 -6
- package/dist/exec/run/change-scope.js +365 -0
- package/dist/exec/run/deferred-cleanup.js +31 -0
- package/dist/exec/run/in-place.js +4 -1
- package/dist/exec/run/job-lock.js +66 -0
- package/dist/exec/run/job-sequence.js +137 -0
- package/dist/exec/run/job.js +56 -19
- package/dist/exec/run/lifecycle-commands.js +1 -1
- package/dist/exec/run/lock.js +22 -1
- package/dist/exec/run/register-command.js +8 -5
- package/dist/exec/run/register-mode.js +68 -8
- package/dist/exec/run/register-resume.js +68 -14
- package/dist/exec/run/register-state.js +13 -8
- package/dist/exec/run/register-worktree.js +140 -125
- package/dist/exec/run/schedule-mode.js +75 -14
- package/dist/exec/run/schedule-prepare.js +3 -0
- package/dist/exec/run/schedule-task.js +88 -38
- package/dist/exec/run/shared.js +5 -0
- package/dist/exec/schedule/schedule.js +116 -4
- package/dist/exec/shared.js +1 -1
- package/dist/exec/smoke.js +190 -0
- package/dist/exec/strategy.js +13 -3
- package/dist/exec/task-view.js +6 -4
- package/dist/exec/trial-commands.js +5 -2
- package/dist/exec/trial-core.js +6 -1
- package/dist/exec/validation-metrics.js +181 -0
- package/dist/exec/worktree-cleanup-lock.js +26 -0
- package/dist/exec/worktree-command.js +9 -1
- package/dist/exec/worktree-ops-commit.js +2 -2
- package/dist/exec/worktree.js +13 -2
- package/dist/grade/command-apply.js +3 -3
- package/dist/grade/command-inspect.js +5 -3
- package/dist/grade/command-plan.js +1 -1
- package/dist/grade/command-run.js +5 -1
- package/dist/grade/run.js +64 -8
- package/dist/job/definition.js +84 -8
- package/dist/job/job.js +79 -23
- package/dist/register/authoring-sources.js +22 -16
- package/dist/register/maintenance-commands.js +2 -2
- package/dist/register/register.js +31 -7
- package/dist/routine/definition.js +9 -0
- package/dist/routine/routine.js +137 -43
- package/dist/routine/status.js +62 -0
- package/dist/schedule/schedule.js +38 -39
- package/dist/shared/agent-types.js +5 -0
- package/dist/shared/cross-process-lock.js +9 -1
- package/dist/shared/dist-freshness.js +8 -2
- package/dist/shared/git-environment.js +2 -1
- package/dist/shared/git.js +44 -1
- package/dist/shared/lefthook-scaffold.js +3 -0
- package/dist/shared/local-config.js +244 -0
- package/dist/shared/specdojo-config.js +34 -20
- package/dist/shared/specdojo-gitignore.js +1 -0
- package/dist/shared/text.js +9 -1
- package/dist/shared/where-alias.js +13 -0
- package/dist/specdojo.js +4 -0
- package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +2 -0
- package/docs/ja/specdojo/guides/exec-config-guide.md +23 -4
- package/docs/ja/specdojo/guides/exec-operation-guide.md +44 -1
- package/docs/ja/specdojo/guides/job-sequence-guide.md +77 -0
- package/docs/ja/specdojo/guides/quick-start-guide.md +3 -3
- package/docs/ja/specdojo/guides/register-operation-guide.md +1 -1
- package/docs/ja/specdojo/guides/routine-operation-guide.md +11 -6
- package/docs/ja/specdojo/guides/schedule-design-guide.md +20 -17
- package/docs/ja/specdojo/guides/waza-guide.md +12 -8
- package/docs/ja/specdojo/recipes/bac-recipe.md +66 -49
- package/docs/ja/specdojo/recipes/bes-recipe.md +90 -54
- package/docs/ja/specdojo/recipes/bps-recipe.md +88 -139
- package/docs/ja/specdojo/recipes/br-recipe.md +40 -47
- package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +97 -109
- package/docs/ja/specdojo/recipes/cdfd-recipe.md +85 -146
- package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +91 -110
- package/docs/ja/specdojo/recipes/cnd-recipe.md +79 -69
- package/docs/ja/specdojo/recipes/cpd-recipe.md +78 -64
- package/docs/ja/specdojo/recipes/cxd-recipe.md +92 -75
- package/docs/ja/specdojo/recipes/ifd-recipe.md +79 -68
- package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +78 -105
- package/docs/ja/specdojo/recipes/ifx-index-recipe.md +105 -71
- package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +60 -49
- package/docs/ja/specdojo/recipes/pm-members-recipe.md +50 -51
- package/docs/ja/specdojo/recipes/pm-organization-recipe.md +59 -51
- package/docs/ja/specdojo/recipes/pm-plan-recipe.md +69 -56
- package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +37 -56
- package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -53
- package/docs/ja/specdojo/recipes/pm-roles-recipe.md +52 -79
- package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +64 -93
- package/docs/ja/specdojo/recipes/prj-charter-recipe.md +71 -106
- package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +78 -157
- package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +62 -111
- package/docs/ja/specdojo/recipes/prj-scope-recipe.md +67 -123
- package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +60 -96
- package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +61 -105
- package/docs/ja/specdojo/recipes/stsd-recipe.md +79 -109
- package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +78 -55
- package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +82 -73
- package/docs/ja/specdojo/recipes/sysd-index-recipe.md +78 -59
- package/docs/ja/specdojo/recipes/tsd-recipe.md +149 -129
- package/docs/ja/specdojo/references/command-reference.md +257 -117
- package/docs/ja/specdojo/references/deliverables-reference.md +21 -12
- package/docs/ja/specdojo/references/specdojo-config-reference.md +37 -2
- package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +101 -257
- package/docs/ja/specdojo/rulebooks/atc-rulebook.md +102 -228
- package/docs/ja/specdojo/rulebooks/bac-rulebook.md +19 -28
- package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +16 -67
- package/docs/ja/specdojo/rulebooks/bds-rulebook.md +30 -51
- package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +41 -61
- package/docs/ja/specdojo/rulebooks/bes-rulebook.md +22 -50
- package/docs/ja/specdojo/rulebooks/bps-rulebook.md +24 -56
- package/docs/ja/specdojo/rulebooks/br-rulebook.md +13 -38
- package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +41 -76
- package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +18 -93
- package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +18 -52
- package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +109 -147
- package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +80 -108
- package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +21 -46
- package/docs/ja/specdojo/rulebooks/cdr-rulebook.md +144 -0
- package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +27 -48
- package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +37 -50
- package/docs/ja/specdojo/rulebooks/clis-rulebook.md +52 -69
- package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +33 -86
- package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +16 -32
- package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +45 -131
- package/docs/ja/specdojo/rulebooks/cop-rulebook.md +69 -275
- package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +20 -112
- package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +23 -56
- package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +12 -145
- package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +39 -47
- package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +37 -56
- package/docs/ja/specdojo/rulebooks/dct-rulebook.md +118 -175
- package/docs/ja/specdojo/rulebooks/dec-rulebook.md +5 -14
- package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +22 -66
- package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +36 -94
- package/docs/ja/specdojo/rulebooks/dss-rulebook.md +59 -81
- package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +31 -131
- package/docs/ja/specdojo/rulebooks/etc-rulebook.md +50 -104
- package/docs/ja/specdojo/rulebooks/gl-rulebook.md +51 -61
- package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +38 -45
- package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +14 -20
- package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +26 -38
- package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +26 -107
- package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +42 -49
- package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +14 -22
- package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +21 -44
- package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +41 -64
- package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +14 -38
- package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +34 -61
- package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +27 -50
- package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +70 -199
- package/docs/ja/specdojo/rulebooks/itc-rulebook.md +65 -153
- package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +74 -150
- package/docs/ja/specdojo/rulebooks/mm-rulebook.md +11 -23
- package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +99 -176
- package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +35 -61
- package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +75 -117
- package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +31 -60
- package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +26 -81
- package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +32 -70
- package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +45 -87
- package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +48 -101
- package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +44 -80
- package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +59 -127
- package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +31 -50
- package/docs/ja/specdojo/rulebooks/opd-rulebook.md +42 -109
- package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +29 -42
- package/docs/ja/specdojo/rulebooks/opr-rulebook.md +29 -87
- package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +62 -84
- package/docs/ja/specdojo/rulebooks/otp-rulebook.md +11 -61
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +91 -106
- package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +25 -34
- package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +30 -53
- package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +23 -35
- package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +27 -45
- package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +37 -45
- package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +45 -46
- package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +37 -48
- package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +25 -29
- package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +28 -35
- package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +36 -41
- package/docs/ja/specdojo/rulebooks/pr-rulebook.md +5 -18
- package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +16 -37
- package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +23 -97
- package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +39 -57
- package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +43 -116
- package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +16 -51
- package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +47 -92
- package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +25 -84
- package/docs/ja/specdojo/rulebooks/sac-rulebook.md +44 -107
- package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +39 -49
- package/docs/ja/specdojo/rulebooks/sf-rulebook.md +42 -49
- package/docs/ja/specdojo/rulebooks/sld-rulebook.md +64 -89
- package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +90 -189
- package/docs/ja/specdojo/rulebooks/stc-rulebook.md +45 -105
- package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +6 -12
- package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +49 -68
- package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +51 -60
- package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +46 -50
- package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +39 -64
- package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +47 -60
- package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +69 -70
- package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +65 -72
- package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +35 -46
- package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +49 -66
- package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +64 -139
- package/docs/ja/specdojo/rulebooks/uis-rulebook.md +41 -108
- package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +49 -144
- package/docs/ja/specdojo/rulebooks/utc-rulebook.md +67 -155
- package/docs/ja/specdojo/samples/bds-sample.md +58 -71
- package/docs/ja/specdojo/samples/bes-index-sample.md +20 -37
- package/docs/ja/specdojo/samples/bes-sample.md +43 -53
- package/docs/ja/specdojo/samples/bps-sample.md +42 -54
- package/docs/ja/specdojo/samples/br-sample.md +40 -52
- package/docs/ja/specdojo/samples/ccd-sample.md +0 -1
- package/docs/ja/specdojo/samples/cdr-sample.md +78 -0
- package/docs/ja/specdojo/samples/cdsd-sample.md +47 -63
- package/docs/ja/specdojo/samples/clis-sample.md +70 -77
- package/docs/ja/specdojo/samples/dec-sample.md +2 -3
- package/docs/ja/specdojo/samples/ifx-api-sample.yaml +0 -2
- package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +0 -2
- package/docs/ja/specdojo/samples/job-sequence.yaml +67 -0
- package/docs/ja/specdojo/samples/mip-index-sample.md +98 -20
- package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +26 -19
- package/docs/ja/specdojo/samples/pm-organization-sample.md +39 -50
- package/docs/ja/specdojo/samples/pm-plan-sample.md +61 -67
- package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +31 -45
- package/docs/ja/specdojo/samples/pm-raci-sample.md +31 -37
- package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +32 -48
- package/docs/ja/specdojo/samples/prj-charter-sample.md +42 -59
- package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +55 -61
- package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +30 -33
- package/docs/ja/specdojo/samples/sf-index-sample.md +13 -55
- package/docs/ja/specdojo/samples/sf-sample.md +73 -85
- package/docs/ja/specdojo/samples/sld-sample.md +60 -79
- package/docs/ja/specdojo/samples/uis-sample.md +98 -121
- package/docs/ja/specdojo/standards/job-definition-standard.md +24 -9
- package/docs/ja/specdojo/templates/cdr-template.md +58 -0
- package/docs/specdojo/schemas/v1/exec-common.schema.yaml +2 -1
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +42 -5
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +35 -0
- package/docs/specdojo/schemas/v1/job-run.schema.yaml +23 -0
- package/docs/specdojo/schemas/v1/job.schema.yaml +63 -2
- package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +2 -2
- package/package.json +9 -6
- package/templates/antigravity/orchestrator.md +4 -1
- package/templates/claude/agents/specdojo-orchestrator.md +4 -1
- package/templates/codex/agents/specdojo-orchestrator.toml +4 -1
- package/templates/codex/orchestrator.md +4 -1
- package/templates/init-exec-defaults.yaml +13 -0
- package/templates/lefthook/tools/specdojo-pre-commit.mjs +8 -0
- package/templates/opencode/agents/specdojo-orchestrator.md +5 -2
|
@@ -24,7 +24,7 @@ External File Exchange Specification Authoring Rulebook
|
|
|
24
24
|
|
|
25
25
|
1. **目的**: システム間・プロセス間で授受されるデータファイルおよび状態ファイルの契約を YAML 1 ファイルで明確化し、書き手(送信元)と読み手(受信先)の認識齟齬および異常時の対応漏れを防ぎます。
|
|
26
26
|
2. **適用範囲**: CSV、TSV、JSON、XML 等のファイルを介して行われるバッチ連携、データ受け渡し、および実行パイプライン段間のエビデンス・状態ファイル連携仕様に適用します。
|
|
27
|
-
3.
|
|
27
|
+
3. **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status` の昇格と承認、改訂と廃止、未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従い、本書と成果物で言い直しません。文書の整形・lint はリポジトリの検証で扱い、業務の検証に含めません。
|
|
28
28
|
|
|
29
29
|
### 1.2. 記載原則と責務境界
|
|
30
30
|
|
|
@@ -34,18 +34,7 @@ External File Exchange Specification Authoring Rulebook
|
|
|
34
34
|
- 外部コマンドやエージェントが生成・参照するファイル自体の永続化契約・必須項目・破損時の扱いを独立して合意・検証する必要がある場合は、本ルール(`ifx-file`)で定義します。
|
|
35
35
|
3. **正本の参照と二重管理の防止**: データ構造の完全な定義が外部スキーマ(JSON Schema、XSD 等)や実装コードの型定義に存在する場合は、`schema_ref` または `schema.references` で正本を参照し、全項目の再掲を避けます。
|
|
36
36
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
| 対象者 | 解決する課題 | 確認・合意する内容 |
|
|
40
|
-
| -------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------- |
|
|
41
|
-
| 業務分析担当(BA)・プロダクトオーナー(PO) | 連携目的や異常時の業務継続可否を判断できない | 対象データ範囲、送信元・受信先の責任分界、欠落・遅延時の業務代替手段と公開可否 |
|
|
42
|
-
| アーキテクト(ARC) | 一覧・他契約との重複や競合書き込みリスクが生じる | `ifx-index` との対応、伝送手段、`atomic_write` 等の技術制約、正本スキーマとの責務分離 |
|
|
43
|
-
| 開発者(DEV) | 生成・読取・検証ロジックの実装条件が定まらない | 配置場所、命名規則、文字コード・改行コード、必須項目、パース失敗・I/O 異常時の分岐動作 |
|
|
44
|
-
| 品質保証担当(QE)・運用担当(OPS) | 異常時の合否判定と復旧手順を確認できない | 正常受領条件、`missing` / `malformed` / `transport_failure` の検知基準と退避・再実行手順 |
|
|
45
|
-
|
|
46
|
-
## 2. 位置づけと用語定義
|
|
47
|
-
|
|
48
|
-
### 2.1. 外部システムI/F一覧および関連仕様との関係
|
|
37
|
+
## 2. 位置づけ
|
|
49
38
|
|
|
50
39
|
```mermaid
|
|
51
40
|
flowchart LR
|
|
@@ -56,17 +45,7 @@ flowchart LR
|
|
|
56
45
|
|
|
57
46
|
1. **一覧からの詳細化**: 本仕様は [[specdojo:ifx-index-rulebook|外部システムI/F一覧作成ルール]] に従う `ifx-index` に登録されたファイル連携(`kind: ファイル`、または外部コマンド連携等で授受するファイル契約)の詳細仕様として位置づけます。
|
|
58
47
|
2. **ID の対応**: `ifx-index` 側の `spec_ref` に記載された文書 ID(例: `prj-0001:ifx-file-agent-evidence`)と、本仕様の `x-spec-meta.id` を一致させます。
|
|
59
|
-
|
|
60
|
-
### 2.2. 用語定義
|
|
61
|
-
|
|
62
|
-
| 用語 | 本書での意味 |
|
|
63
|
-
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
64
|
-
| `source`(送信元・生成元) | 連携契約においてファイルを生成・提供する側のシステム、コンポーネント、またはロール |
|
|
65
|
-
| `target`(受信先・利用先) | 連携契約においてファイルを受領・消費する側のシステム、コンポーネント、またはロール |
|
|
66
|
-
| `writer`(書込主体) | 個別ファイルを実際に作成・更新する主体および書き込み契機。双方向連携や複数ファイル連携でファイルごとに明示する |
|
|
67
|
-
| `reader`(読取主体) | 個別ファイルを実際に読み取り・検証・後続処理へ渡す主体および利用目的 |
|
|
68
|
-
| `direction`(連携方向) | `source` と `target` 間のデータの向き(`source_to_target` / `target_to_source` / `bidirectional`) |
|
|
69
|
-
| `atomic_write`(アトミック書込) | 書き込み途中の不完全なファイルが読み手に参照されることを防ぐため、一時ファイル出力後にリネーム等で置換する書き込み方式 |
|
|
48
|
+
3. **契約の主体とファイルの主体**: `source` / `target` は連携契約全体の送信元・受信先、`writer` / `reader` は個別ファイルを実際に書く・読む主体です。報告内容の作り手とファイルの書き手が異なる場合は、`writer` にファイルの書き手を書きます。
|
|
70
49
|
|
|
71
50
|
## 3. ファイル命名・ID規則
|
|
72
51
|
|
|
@@ -85,11 +64,11 @@ flowchart LR
|
|
|
85
64
|
|
|
86
65
|
## 4. 推奨 Frontmatter・メタ情報項目
|
|
87
66
|
|
|
88
|
-
|
|
67
|
+
共通メタ情報の原則は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] を正本とします。
|
|
89
68
|
|
|
90
69
|
### 4.1. スキーマ宣言とメタ情報(x-spec-meta)の構成
|
|
91
70
|
|
|
92
|
-
YAML 成果物の先頭にはスキーマ検証用の modeline コメント(専用スキーマが未整備の場合は `# specdojo-schema: none reason=no-ifx-file-schema`)を記載し、ルートキー `x-spec-meta`
|
|
71
|
+
YAML 成果物の先頭にはスキーマ検証用の modeline コメント(専用スキーマが未整備の場合は `# specdojo-schema: none reason=no-ifx-file-schema`)を記載し、ルートキー `x-spec-meta` 配下にメタ情報を定義します。`none` は構造の検証だけを省き、`x-spec-meta.type` と rulebook 宣言の照合はリポジトリの schema 検証で省かれません。
|
|
93
72
|
|
|
94
73
|
```yaml
|
|
95
74
|
# specdojo-schema: none reason=no-ifx-file-schema
|
|
@@ -105,18 +84,16 @@ x-spec-meta:
|
|
|
105
84
|
|
|
106
85
|
### 4.2. メタ情報の各フィールド定義
|
|
107
86
|
|
|
108
|
-
| フィールド名 | 必須 | 型 | 説明
|
|
109
|
-
| ------------ | ---- | ------ |
|
|
110
|
-
| `id` | ○ | string | 仕様の一意な ID。ファイル名および `ifx-index` の `spec_ref` と対応させます。
|
|
111
|
-
| `type` | ○ | string | `api` 固定。本 rulebook の `deliverable_type: api` と一致させます(`file` 等の別値を指定してはなりません)。
|
|
112
|
-
| `status` | ○ | string | 文書のライフサイクル状態(`draft` / `ready` / `deprecated
|
|
113
|
-
| `title` | ○ | string | 対象ファイルまたは連携契約を識別できる日本語名称。
|
|
114
|
-
| `rulebook` | ○ | string | 準拠する rulebook ID(`specdojo:ifx-file-rulebook` 固定)。
|
|
115
|
-
| `part_of` | 任意 | array | 所属する上位文書 ID の配列。
|
|
116
|
-
| `based_on` | 任意 | array | 根拠となる上位文書 ID(`ifx-index` 等)の配列。未作成の文書や無関係な ID は記載しません。
|
|
117
|
-
| `supersedes` | 任意 | array | 置き換え元の旧仕様 ID の配列。
|
|
118
|
-
|
|
119
|
-
- 同梱の完成例(sample)は、業務背景・運用手順・異常系リカバリの解説を伴う Markdown 文書(Frontmatter の `type: api`、`rulebook: specdojo:ifx-file-rulebook`)として構成し、その本文中に本章および第5章の必須構造を満たす YAML 定義を掲載します。
|
|
87
|
+
| フィールド名 | 必須 | 型 | 説明 |
|
|
88
|
+
| ------------ | ---- | ------ | ------------------------------------------------------------------------------------------------------------ |
|
|
89
|
+
| `id` | ○ | string | 仕様の一意な ID。ファイル名および `ifx-index` の `spec_ref` と対応させます。 |
|
|
90
|
+
| `type` | ○ | string | `api` 固定。本 rulebook の `deliverable_type: api` と一致させます(`file` 等の別値を指定してはなりません)。 |
|
|
91
|
+
| `status` | ○ | string | 文書のライフサイクル状態(`draft` / `ready` / `deprecated`)。 |
|
|
92
|
+
| `title` | ○ | string | 対象ファイルまたは連携契約を識別できる日本語名称。 |
|
|
93
|
+
| `rulebook` | ○ | string | 準拠する rulebook ID(`specdojo:ifx-file-rulebook` 固定)。 |
|
|
94
|
+
| `part_of` | 任意 | array | 所属する上位文書 ID の配列。 |
|
|
95
|
+
| `based_on` | 任意 | array | 根拠となる上位文書 ID(`ifx-index` 等)の配列。未作成の文書や無関係な ID は記載しません。 |
|
|
96
|
+
| `supersedes` | 任意 | array | 置き換え元の旧仕様 ID の配列。 |
|
|
120
97
|
|
|
121
98
|
## 5. 本文要件
|
|
122
99
|
|
|
@@ -156,14 +133,12 @@ YAML のルートには以下のキーを配置します。
|
|
|
156
133
|
|
|
157
134
|
### 5.3. 連携方向と参加者(source, target, direction)
|
|
158
135
|
|
|
159
|
-
1. `source`:
|
|
160
|
-
2. `
|
|
161
|
-
3. `direction`: `source_to_target`(送信元から受信先への単方向)、`target_to_source`(受信先から送信元への単方向)、`bidirectional`(段間遷移や状態ファイル更新など双方向の授受)のいずれかを指定します。
|
|
136
|
+
1. `source` / `target`: システム名またはコンポーネント名で書きます。
|
|
137
|
+
2. `direction`: 段間遷移や状態ファイル更新など、双方が書き読みする授受は `bidirectional` とします。
|
|
162
138
|
|
|
163
139
|
### 5.4. フォーマットと連携契機(format, timing)
|
|
164
140
|
|
|
165
|
-
1. `
|
|
166
|
-
2. `timing`: 定期バッチの実行時刻(例: `毎週日曜日 21:30`、`毎日営業終了後 21:00`)またはイベント・状態遷移の契機(例: `executor 完了直後、親検証完了時、reporter 起動前後`)を検証可能な条件として記述します。
|
|
141
|
+
1. `timing`: 定期バッチの実行時刻(例: `毎週日曜日 21:30`、`毎日営業終了後 21:00`)またはイベント・状態遷移の契機(例: `executor 完了直後、親検証完了時、reporter 起動前後`)を検証可能な条件として記述します。
|
|
167
142
|
|
|
168
143
|
### 5.5. 受け渡し方法(transport)
|
|
169
144
|
|
|
@@ -199,11 +174,11 @@ YAML のルートには以下のキーを配置します。
|
|
|
199
174
|
|
|
200
175
|
1. **判断基準**: 誰がいつファイルを書き(`source` / `writer`)、誰が何のために読み(`target` / `reader`)、どこにどの名前で置かれるか(`location` / `naming_rule`)が、実装コードを見ずに特定できること。
|
|
201
176
|
2. **単一ファイルと複数ファイルの使い分け**: 1 つのファイルだけで完結する連携は `file` を使い、実行エビデンス(`evidence.json`)とパイプライン状態(`pipeline-state.json`)のように同一実行単位で協調動作するファイル群は `files` 配列で定義し、ファイルごとに `writer`・`reader`・`required_fields` を明記します。
|
|
202
|
-
3. **仮置き・前提条件の明記**: 通信環境や運用体制に関する前提条件、または未確定の技術判断がある場合は、YAML コメントで `# _ASSUMPTION_:` や `# _UNDECIDED_:`
|
|
177
|
+
3. **仮置き・前提条件の明記**: 通信環境や運用体制に関する前提条件、または未確定の技術判断がある場合は、YAML コメントで `# _ASSUMPTION_:` や `# _UNDECIDED_:` を付記し、何が決まれば解消するかを書きます。
|
|
203
178
|
|
|
204
179
|
### 6.2. 受け渡し条件と構造定義の判断基準
|
|
205
180
|
|
|
206
|
-
1. **判断基準**:
|
|
181
|
+
1. **判断基準**: 下流の実装者がパーサ・バリデータ・ファイル配置処理を実装でき、テスト担当が正常データと境界値・異常データのテストケースを導出できること。
|
|
207
182
|
2. **インライン定義と正本参照の選択**:
|
|
208
183
|
- 外部取引先(問屋や外部システム)との CSV / JSON 連携など、リポジトリ内に別途スキーマ定義が存在しない場合は、`schema.fields` に型・必須性・制約(`constraints`)・マッピング(`mapping`)を具体的に記述します。
|
|
209
184
|
- 同一システム内のランナーとエージェント間の契約など、TypeScript 型定義や JSON Schema が正本として存在する場合は、`files[].schema_ref` および `schema.references` で正本パスを指し、`files[].required_fields` に必須キーを列挙して二重管理を防ぎます。
|
|
@@ -217,56 +192,15 @@ YAML のルートには以下のキーを配置します。
|
|
|
217
192
|
|
|
218
193
|
#### 6.4.1. 良い例: 正本参照・書き手と読み手・異常時動作の明確化
|
|
219
194
|
|
|
220
|
-
|
|
221
|
-
# specdojo-schema: none reason=no-ifx-file-schema
|
|
222
|
-
x-spec-meta:
|
|
223
|
-
id: prj-0001:ifx-file-agent-evidence
|
|
224
|
-
type: api
|
|
225
|
-
status: draft
|
|
226
|
-
title: 外部ファイル連携仕様(agent の evidence)
|
|
227
|
-
rulebook: specdojo:ifx-file-rulebook
|
|
228
|
-
based_on:
|
|
229
|
-
- prj-0001:ifx-index
|
|
195
|
+
書き手と読み手、正本参照と必須項目、異常時の動作に絞った抜粋です。
|
|
230
196
|
|
|
197
|
+
```yaml
|
|
231
198
|
files:
|
|
232
199
|
- name: evidence.json
|
|
233
|
-
naming_rule: evidence.json
|
|
234
|
-
location: docs/ja/projects/<project-id>/execution/runs/<origin>/<item-id>/<run-id>/evidence.json
|
|
235
|
-
description: タスク実行における変更内容・検証結果・最終メッセージを記録する構造化エビデンス
|
|
236
200
|
writer: SpecDojo runner(agent の stdout から抽出・正規化して書き込み)
|
|
237
201
|
reader: SpecDojo runner(検証合否判定、reporter への入力、result.md 反映)
|
|
238
|
-
format: JSON
|
|
239
|
-
encoding: UTF-8
|
|
240
202
|
schema_ref: src/exec/evidence.ts#ExecEvidence
|
|
241
|
-
required_fields:
|
|
242
|
-
- schema_version
|
|
243
|
-
- task_id
|
|
244
|
-
- run_id
|
|
245
|
-
- stage
|
|
246
|
-
- changes
|
|
247
|
-
- diff_summary
|
|
248
|
-
- validations
|
|
249
|
-
- final_message
|
|
250
|
-
|
|
251
|
-
source: AI provider CLI(executor / reporter agent)および SpecDojo runner
|
|
252
|
-
target: SpecDojo runner および結果報告(reporter)
|
|
253
|
-
direction: bidirectional
|
|
254
|
-
format: JSON
|
|
255
|
-
timing: タスク実行サイクルの各段遷移時(executor 完了直後、親検証完了時、reporter 起動前後)
|
|
256
|
-
|
|
257
|
-
transport:
|
|
258
|
-
method: ローカルファイルシステム
|
|
259
|
-
endpoint: <executionPath>/runs/<origin>/<itemId>/<runId>/
|
|
260
|
-
frequency: タスク実行ごとに都度
|
|
261
|
-
atomic_write: 一時ファイル(.tmp)へ書き込み後に renameSync でアトミック置換を実施
|
|
262
|
-
|
|
263
|
-
schema:
|
|
264
|
-
json:
|
|
265
|
-
root_type: object
|
|
266
|
-
content_type: application/json
|
|
267
|
-
encoding: UTF-8
|
|
268
|
-
references:
|
|
269
|
-
evidence_spec: src/exec/evidence.ts
|
|
203
|
+
required_fields: [schema_version, task_id, run_id, stage, changes, validations, final_message]
|
|
270
204
|
|
|
271
205
|
error_handling:
|
|
272
206
|
missing:
|
|
@@ -286,7 +220,6 @@ error_handling:
|
|
|
286
220
|
x-spec-meta:
|
|
287
221
|
id: ifx-file-bad-example
|
|
288
222
|
type: file # 禁止: deliverable_type と不整合(api 固定)
|
|
289
|
-
status: ready # 禁止: AI エージェントによる ready 昇格
|
|
290
223
|
title: 連携仕様
|
|
291
224
|
rulebook: specdojo:ifx-file-rulebook
|
|
292
225
|
|
|
@@ -314,25 +247,11 @@ error_handling:
|
|
|
314
247
|
| 正本スキーマや型定義の全文コピー&ペーストによる再掲 | 正本との二重管理になり、フィールド変更時に仕様間の不整合を引き起こすため |
|
|
315
248
|
| DB 物理テーブル名、SQL 文、内部クラス名などの内部実装詳細の記載 | 外部インターフェース契約と内部設計の責務境界が混同されるため |
|
|
316
249
|
| 接続パスワード、秘密鍵、API トークン、個人情報の実データの直接記載 | セキュリティおよび機密保護上のリスクを防ぐため |
|
|
317
|
-
| 「適切に処理する」「問題ないようにする」等の検証不能な曖昧表現 |
|
|
318
|
-
| 本 rulebook 本文への同梱 `sample` / `recipe` / `template` の wikilink 設置 | 対応関係は Frontmatter で宣言し、本文の自己完結性と構造標準を保つため |
|
|
250
|
+
| 「適切に処理する」「問題ないようにする」等の検証不能な曖昧表現 | 実装の分岐および合否判定の基準として機能しないため |
|
|
319
251
|
|
|
320
252
|
## 8. 運用ルール
|
|
321
253
|
|
|
322
254
|
### 8.1. 成果物の検証手順
|
|
323
255
|
|
|
324
|
-
1.
|
|
325
|
-
2.
|
|
326
|
-
|
|
327
|
-
### 8.2. 改訂・廃止とライフサイクル変更管理
|
|
328
|
-
|
|
329
|
-
成果物の改訂・廃止、置き換え(`supersedes`)、非推奨化(`status: deprecated`)は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] の「文書の改訂・廃止とライフサイクル変更管理」に従い、以下の役割分担で影響を追跡します。
|
|
330
|
-
|
|
331
|
-
| Role code | 改訂・廃止時の確認対象と責務 |
|
|
332
|
-
| --------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
333
|
-
| `BA` | 外部システムI/F一覧(`ifx-index`)、業務プロセス、成果物カタログの記載と対象範囲の整合を確認する |
|
|
334
|
-
| `ARC` | `transport` の方式・安全性、正本スキーマ参照(`schema_ref` / `references`)、関連する `ifx-cmd` との境界を確認する |
|
|
335
|
-
| `DEV` | ファイル生成・読取ロジック、`atomic_write` 実装、正本型定義・スキーマとの一致を確認し追従修正を行う |
|
|
336
|
-
| `QE` | 正常受領条件および `missing` / `malformed` / `transport_failure` の異常系テストケース・受入基準への影響を確認する |
|
|
337
|
-
| `PM` | 仕様変更に伴う関連成果物・スケジュールタスク・プロジェクト登録簿(PJR)の追従作業を管理する |
|
|
338
|
-
| `PO` | 仕様の合意確定(`status: ready` への昇格)、旧仕様の置き換え(`supersedes`)、および廃止(`deprecated`)を判断する |
|
|
256
|
+
1. **一覧・正本との照合**: `ifx-index` の `spec_ref` と `x-spec-meta.id` が一致し、`schema_ref` / `references` の参照先が実在して、`files[].required_fields` が正本の必須項目と矛盾しないことを確かめます。欠落や不一致が 1 件でもあれば不合格とし、正本に合わせて直します。
|
|
257
|
+
2. **異常系の導出**: `error_handling` の 3 区分(`missing`、`malformed`、`transport_failure`)と `required_fields` から正常系・異常系の確認ケースを導出し、各ケースで継続・停止、ファイルの保持・退避、再試行・引き継ぎの期待結果が一意に決まることを確かめます。
|
|
@@ -22,46 +22,40 @@ External System Interface List Documentation Rules
|
|
|
22
22
|
- 連携目的と成功後に得る結果を `name` とコメントで示す。目的、相手、タイミング、失敗の影響が異なる契約は別要素にする。
|
|
23
23
|
- 一覧には連携境界と異常時の判断を残す。引数、データ項目、接続先、認証値、終了コード表、再試行の数値は詳細仕様・設定・リファレンスへ委譲する。
|
|
24
24
|
- 未決の方式や仮置きの範囲を合意済みとして記さない。未決事項・合意・計画への引き継ぎはコメントで扱い、schema にない管理用キーを追加しない。
|
|
25
|
+
- **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status`・承認・改訂と廃止・未決事項の引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint はリポジトリの検証で扱い、業務の受入確認に含めない。
|
|
25
26
|
|
|
26
|
-
## 2.
|
|
27
|
+
## 2. 位置づけ
|
|
27
28
|
|
|
28
|
-
|
|
29
|
-
| ------------------- | ---------------------------------------------------------------------------------- |
|
|
30
|
-
| 外部システムI/F一覧 | 連携スコープと詳細契約への入口。内部の関数・全依存パッケージの一覧にはしない |
|
|
31
|
-
| 連携境界 | 対象システムと、別システム・外部プロセス・外部管理データの間の受け渡し |
|
|
32
|
-
| 詳細 I/F 仕様 | プロトコル、認証、入出力、失敗・回復条件を定義する契約。`spec_ref` で対応づける |
|
|
33
|
-
| 結合テスト | 一覧の連携名と詳細仕様から正常・失敗時の対象を選ぶ。テスト手順は本一覧へ展開しない |
|
|
34
|
-
|
|
35
|
-
要求や業務判断の理由は上位の正本に置く。一覧で必要な影響だけを要約し、技術方式の選択を業務承認の代わりにしない。
|
|
29
|
+
連携境界は、対象システムと別システム・外部プロセス・外部管理データの間の受け渡しを指す。一覧は上位の要求を受けて詳細 I/F 仕様へ接続し、連携名と詳細仕様から正常・失敗時の結合テスト対象を選ぶ入口とする。内部の関数・全依存パッケージやテスト手順の一覧にはしない。
|
|
36
30
|
|
|
37
31
|
## 3. ファイル命名・ID規則
|
|
38
32
|
|
|
39
33
|
- 全体一覧は `ifx-index.yaml` とし、外部 I/F 仕様の文書群へ配置する。分割時は領域を表す接尾辞を付け、同じ対象範囲の一覧を複製しない。
|
|
40
|
-
- `id`
|
|
34
|
+
- `id` は修飾 ID とし、ローカル ID は `ifx-index` を基準に対象範囲内で一意にする。許容形式は `docs/specdojo/schemas/v1/ifx-index.schema.yaml` を正本とし、独自の正規表現で制限しない。
|
|
41
35
|
- 連携名は一覧内で一意にし、改称・分割時は旧名との対応をコメントへ残す。位置番号を連携の識別子として使用しない。
|
|
42
|
-
-
|
|
36
|
+
- 連携の追加・廃止・方式変更では、影響する詳細仕様、実装範囲、結合テスト対象と、連携スコープの変化を特定する。
|
|
43
37
|
|
|
44
38
|
## 4. 先頭メタ項目
|
|
45
39
|
|
|
46
40
|
YAML のトップレベルへメタ情報を置く。必須キー、値域、型、参照形式は `docs/specdojo/schemas/v1/ifx-index.schema.yaml` を正本とし、ファイル先頭の modeline で参照する。
|
|
47
41
|
|
|
48
42
|
- `id`・`title` は一覧と対象システムを識別できる内容にし、`type` は本系統の成果物種別、`rulebook` は本書の ID とする。
|
|
49
|
-
- `status`
|
|
43
|
+
- `status` の値は `draft`・`ready`・`deprecated` とする。個々の連携の採否・進捗はコメントで区別する。
|
|
50
44
|
- `based_on` は実際の依存関係に含まれる直接の根拠だけを記す。プロジェクト共通文脈や詳細仕様を機械的に転記しない。
|
|
51
45
|
|
|
52
46
|
## 5. 本文要件
|
|
53
47
|
|
|
54
48
|
キーの骨組みは宣言された雛形に置く。本章は各記入領域の目的と判断条件を定め、キーの型・構文は schema へ委譲する。列挙値は選び方に関わるものだけを本章で示す。
|
|
55
49
|
|
|
56
|
-
| 記入領域 | 必須性 | 目的・記述要件
|
|
57
|
-
| ------------------------- | ------ |
|
|
58
|
-
| 冒頭コメント | 必須 |
|
|
59
|
-
| `interfaces` の目的と両端 | 必須 | `name`・`source`・`target` で連携目的と両端を特定する。抽象名だけなら目的をコメントで補う
|
|
60
|
-
| 方向と方式 | 必須 | `direction`・`kind`・`format` で境界上の受け渡しを示す。サービス内部の方式と呼び出し側の方式を混同しない
|
|
61
|
-
| 発生条件 | 必須 | `timing` で業務イベント・操作・周期と、起動する条件を示す。周期が不明なら仮の時刻を固定しない
|
|
62
|
-
| 異常時の判断 | 必須 | `error_handling` に未完了・結果不明になる結果、停止・保留の条件、確認対象と担当を示す。副作用の確認前に再送できると断定しない
|
|
63
|
-
| 詳細への導線 | 必須 | `spec_ref` に実在する対応仕様 ID を置く。未整備・対応未確認なら `TBD` とし、「詳細参照と未決事項」の情報をコメントに残す
|
|
64
|
-
| 合意・管理への導線 | 必須 | IF
|
|
50
|
+
| 記入領域 | 必須性 | 目的・記述要件 |
|
|
51
|
+
| ------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
52
|
+
| 冒頭コメント | 必須 | 対象範囲・境界・主要な対象外を示す。仮定や未決のスコープはラベルで区別する |
|
|
53
|
+
| `interfaces` の目的と両端 | 必須 | `name`・`source`・`target` で連携目的と両端を特定する。抽象名だけなら目的をコメントで補う |
|
|
54
|
+
| 方向と方式 | 必須 | `direction`・`kind`・`format` で境界上の受け渡しを示す。サービス内部の方式と呼び出し側の方式を混同しない |
|
|
55
|
+
| 発生条件 | 必須 | `timing` で業務イベント・操作・周期と、起動する条件を示す。周期が不明なら仮の時刻を固定しない |
|
|
56
|
+
| 異常時の判断 | 必須 | `error_handling` に未完了・結果不明になる結果、停止・保留の条件、確認対象と担当を示す。副作用の確認前に再送できると断定しない |
|
|
57
|
+
| 詳細への導線 | 必須 | `spec_ref` に実在する対応仕様 ID を置く。未整備・対応未確認なら `TBD` とし、「詳細参照と未決事項」の情報をコメントに残す |
|
|
58
|
+
| 合意・管理への導線 | 必須 | IF ごとの確認者・合意対象をコメントで対応づける。未決事項がある場合は、影響する連携と後続作業、当面の保留範囲を示す |
|
|
65
59
|
|
|
66
60
|
`direction` は指定した `source` と `target` に対して読み、`source` から送るなら `source_to_target`、`target` から受けるなら `target_to_source` とする。要求と応答の両方を一契約として扱う場合は `bidirectional` とし、送信データと受付結果の意味をコメントで区別する。`kind` は境界で受け渡す手段を `API`・`ファイル`・`メッセージ`・`コマンド` から選ぶ。`format` は `CSV`・`JSON`・`XML` から選び、どれにも当たらなければ `その他`、未決なら `TBD` としてコメントで内訳や論点を補う。schema で任意の項目でも、本一覧から下流へ判断を渡すために本章が要求する項目は記入する。
|
|
67
61
|
|
|
@@ -69,9 +63,9 @@ YAML のトップレベルへメタ情報を置く。必須キー、値域、型
|
|
|
69
63
|
|
|
70
64
|
### 6.1. メタ情報と対象範囲
|
|
71
65
|
|
|
72
|
-
- 判断基準:
|
|
73
|
-
- 良い例:
|
|
74
|
-
- 悪い例:
|
|
66
|
+
- 判断基準: どのシステム・利用場面の境界を管理するか、対象外と仮定を含めて識別できること。
|
|
67
|
+
- 良い例: 「店舗端末から本部への商品照会・売上登録を対象とする。仕入先連携は対象外」と冒頭に記す。
|
|
68
|
+
- 悪い例: タイトルを「外部連携」とだけ書いて将来候補を現在の対象へ混ぜる。
|
|
75
69
|
|
|
76
70
|
### 6.2. 連携単位・目的・両端
|
|
77
71
|
|
|
@@ -99,44 +93,43 @@ YAML のトップレベルへメタ情報を置く。必須キー、値域、型
|
|
|
99
93
|
|
|
100
94
|
### 6.6. 詳細参照と未決事項
|
|
101
95
|
|
|
102
|
-
- 判断基準: 実在する契約へ到達できること。`TBD`
|
|
103
|
-
- 良い例: `spec_ref: TBD` に「`_UNDECIDED_:`
|
|
104
|
-
- 悪い例: 説明なしの `TBD
|
|
96
|
+
- 判断基準: 実在する契約へ到達できること。`TBD` や未決の方式には、論点、解消条件、影響する連携・業務・後続作業、当面の扱いをコメントで残す。
|
|
97
|
+
- 良い例: `spec_ref: TBD` に「`_UNDECIDED_:` 売上受付の照合方式が未決。詳細契約と結果不明時の期待結果がそろうまで、売上登録の受入を保留する」と添える。
|
|
98
|
+
- 悪い例: 説明なしの `TBD`、未作成の文書 ID を完成した契約として扱う参照、影響する連携を区別せず一覧全体を完了扱いにする記述。
|
|
105
99
|
|
|
106
|
-
共通条件は一覧冒頭、契約固有条件は詳細仕様を正本とする。詳細仕様が存在しても未決事項があれば `spec_ref`
|
|
100
|
+
共通条件は一覧冒頭、契約固有条件は詳細仕様を正本とする。詳細仕様が存在しても未決事項があれば `spec_ref` だけで解決済みとせず、残る論点と影響を一覧に残す。
|
|
107
101
|
|
|
108
102
|
### 6.7. 合意・計画・課題への引き継ぎ
|
|
109
103
|
|
|
110
|
-
|
|
104
|
+
- 判断基準: 連携名から利用場面・業務影響、契約、期待結果それぞれの確認者と合意対象を特定できること。外部側との調整が必要なら確認窓口も示す。複数 IF で共通なら、連携名を明示してコメントを冒頭または末尾にまとめてよい。
|
|
105
|
+
- 良い例: 「売上登録は店番担当と本部運用窓口が保留時の店頭対応、契約の確認者が受付・回復条件、テストの確認者が結果照合を確認する。認証方式が未合意のため外部結合テストの着手は保留」と記す。
|
|
106
|
+
- 悪い例: 「関係者確認済み」「進捗は順調」だけで合意対象や残る論点を隠す、または一覧に計画・管理簿の期日・進捗表を複製する。
|
|
111
107
|
|
|
112
|
-
|
|
113
|
-
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
114
|
-
| 確認と合意 | 利用場面・業務影響を確認する BA、契約を確認する ARC・DEV、期待結果を確認する QE と合意対象。外部側との調整が必要なら確認窓口も示す | 役割の割当は組織・メンバー定義を参照する。必要な窓口が未特定なら担当 Role と特定する時点を未決事項として残す |
|
|
115
|
-
| 詳細仕様の作成と進捗 | 担当 Role code、未着手・作成中・確認待ちなどの現在の論点、完了条件、期限または判断するマイルストーン、依存する後続作業 | PM が Schedule の作業へ接続する。担当・期日・進捗の正本は計画に置き、一覧には作業 ID と引き継ぎ時点の未完了事項を残す |
|
|
116
|
-
| リスク・課題・変更・決定 | 対象の連携名、発生条件または未決論点、業務・公開・後続仕様・Schedule への影響、対応担当 Role code、報告先、次アクション | PM が PJR または採用済み管理簿へ接続し、PO の判断を決定記録へ残す。一覧には転送先レコードと連携への影響を残す |
|
|
108
|
+
### 6.8. 検証と引き渡しの判定
|
|
117
109
|
|
|
118
|
-
-
|
|
119
|
-
-
|
|
120
|
-
-
|
|
110
|
+
- 対象と方法: 対象範囲の利用場面と各連携を突き合わせ、正常時・失敗時の受け渡しをたどる。「本文要件」の必須領域、連携名の一意性、方向と両端の一致、詳細仕様との対応を照合し、IF ごとの確認者と合意対象を確かめる。
|
|
111
|
+
- 合格条件: 対象内の連携に抜けがなく、目的・発生条件・成功後の結果と、失敗時に止める操作・確認対象・担当を特定できること。詳細仕様が対象操作に対応し、結果不明時に無条件の再送を要求していないこと。
|
|
112
|
+
- 未解消事項の扱い: 詳細仕様が未整備、または方式・期待結果が未合意なら、該当連携の論点と影響、保留する業務・後続作業を明示して引き渡す。ほかの連携と分けて判定し、一覧全体を解消済みとしない。
|
|
121
113
|
|
|
122
|
-
### 6.
|
|
114
|
+
### 6.9. 表示ページでのレビュー
|
|
123
115
|
|
|
124
|
-
|
|
116
|
+
YAML を正本とし、`specdojo yaml-pages build` が同階層の `generated/` へ表形式の表示ページを生成する。レビューは表示ページで行い、修正は YAML へ戻す。
|
|
125
117
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
118
|
+
| ページの部分 | YAML からの取り出し方 |
|
|
119
|
+
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
120
|
+
| 要約の表 | `id`・`status`・`interfaces` の件数・`spec_ref` が `TBD` の件数 |
|
|
121
|
+
| 連携の一覧 | `interfaces` の順に、連携名・`target`・`direction`・`kind`・`format`・`spec_ref`・注記の件数と目印(`_TODO_` など)を 1 行に置く |
|
|
122
|
+
| 連携ごとの詳細 | 連携ごとに、schema の項目(`source`・`timing`・`error_handling` を含む)を表にし、その連携のコメントを注記として続ける |
|
|
123
|
+
| 一覧全体の注記 | `interfaces` の外にある冒頭・末尾のコメント |
|
|
124
|
+
| YAML の正本 | YAML 全文を折りたたんで添える |
|
|
130
125
|
|
|
131
|
-
-
|
|
132
|
-
-
|
|
126
|
+
- 連携のコメントは、連携の直前(`- name` と同じ字下げ)と連携の内側(より深い字下げ)に置いたものとする。行頭から始まるコメントは一覧全体の注記になる。連携に関わる未決事項・留保はこの位置に書く。
|
|
127
|
+
- `spec_ref` は詳細仕様への wikilink にし、プロジェクトの修飾がなければ一覧の `id` の修飾を補う。`TBD` は「未整備(TBD)」と表示する。
|
|
128
|
+
- `direction` は「連携元 → 連携先」「連携先 → 連携元」「双方向」と表示する。表示ページのために schema にないキーを YAML へ足さない。
|
|
133
129
|
|
|
134
130
|
## 7. 禁止事項
|
|
135
131
|
|
|
136
|
-
- 根拠のない接続方式、認証方式、承認済みの範囲を確定情報として記すこと。
|
|
137
132
|
- 連携の目的・失敗影響が異なる操作を、相手が同じという理由だけでまとめること。
|
|
138
|
-
- 認証情報、個人環境の認証パス、秘密値入り URL を記載すること。
|
|
139
133
|
- 引数、ペイロード構造、設定値、再試行回数、終了コード一覧を正本から転載すること。
|
|
140
|
-
-
|
|
141
|
-
- `status` や技術レビューの成功だけで、人間の PO の承認・公開判断を済んだものとすること。
|
|
134
|
+
- 対象操作との対応を確認していない詳細仕様 ID、説明のない `TBD` を残すこと。
|
|
142
135
|
- schema にない担当・期限・進捗・リスクのキーを追加したり、Schedule・管理簿・決定記録を一覧へ複製したりすること。
|
|
@@ -12,28 +12,24 @@ specdojo:
|
|
|
12
12
|
|
|
13
13
|
# 外部メッセージ仕様(External Message Specification: EMS)作成ルール
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
外部システム(物流、決済、会計など)との非同期連携のメッセージング仕様を、**AsyncAPI + CloudEvents**(YAML 1ファイル)で定義します。
|
|
16
16
|
|
|
17
|
-
EMS は ESIL(外部システムIF
|
|
18
|
-
ESIL 側の `spec_ref: ifx-msg-...` は、このEMSのID(およびファイル名)と対応させます。
|
|
17
|
+
EMS は ESIL(外部システムIF一覧)から参照される「詳細仕様」で、ESIL 側の `spec_ref: ifx-msg-...` をこの EMS の ID とファイル名に対応させます。
|
|
19
18
|
|
|
20
|
-
|
|
21
|
-
フォーマットは **AsyncAPI + CloudEvents**(YAML)を正とします。
|
|
19
|
+
`status` の昇格と承認、改訂と廃止は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従い、本書では言い直しません。
|
|
22
20
|
|
|
23
21
|
## 1. ファイル規約
|
|
24
22
|
|
|
25
|
-
- ファイル名: `ifx-msg-<短い英小文字ハイフン>.yaml`
|
|
26
|
-
- ESILからの参照: `spec_ref: ifx-msg-...`(例: `ifx-msg-stock-changed`)
|
|
23
|
+
- ファイル名: `ifx-msg-<短い英小文字ハイフン>.yaml`(例: `ifx-msg-stock-changed`)
|
|
27
24
|
- 1ファイル = 1つのメッセージング仕様(1つのイベント群/チャネル群)
|
|
28
25
|
|
|
29
26
|
## 2. バージョン
|
|
30
27
|
|
|
31
|
-
- **AsyncAPI 2.6.0
|
|
32
|
-
- CloudEvents は **1.0** を前提とする
|
|
28
|
+
- ツール互換性のため **AsyncAPI 2.6.0** を第一候補とし、CloudEvents は **1.0** を前提とします。
|
|
33
29
|
|
|
34
30
|
## 3. 記載方針(必須)
|
|
35
31
|
|
|
36
|
-
-
|
|
32
|
+
- **外部との合意に必要な最小十分**を記載する
|
|
37
33
|
- メッセージのエンベロープは **CloudEvents** とし、イベント属性を明示する
|
|
38
34
|
- チャネル(topic/queue)や方向(publish/subscribe)を明確にする
|
|
39
35
|
- payload(`data`)のスキーマは `components/schemas` に集約し、参照で使い回す
|
|
@@ -51,22 +47,19 @@ ESIL 側の `spec_ref: ifx-msg-...` は、このEMSのID(およびファイル
|
|
|
51
47
|
|
|
52
48
|
- `asyncapi`
|
|
53
49
|
- `info`(`title`, `version` を含む)
|
|
54
|
-
|
|
55
50
|
- `x-spec-meta`(`id`, `type`, `status`, `rulebook` を含む)
|
|
56
51
|
- `channels`(少なくとも1つ)
|
|
57
52
|
- `components/messages`(少なくとも1つ)
|
|
58
53
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
仕様のトレーサビリティ管理のため、以下を `x-spec-meta` に含めます。
|
|
54
|
+
### 4.1. メタ情報(x-spec-meta)
|
|
62
55
|
|
|
63
|
-
| キー | 説明
|
|
64
|
-
| -------- |
|
|
65
|
-
| id | メッセージ仕様ID(`ifx-msg
|
|
66
|
-
| type | `api` 固定
|
|
67
|
-
| rulebook | `specdojo:ifx-msg-rulebook`
|
|
68
|
-
| status |
|
|
69
|
-
| based_on | 根拠となる他仕様のIDリスト(例: `["ifx-api-auth"]`)
|
|
56
|
+
| キー | 説明 | 必須 |
|
|
57
|
+
| -------- | ---------------------------------------------------- | ---- |
|
|
58
|
+
| id | メッセージ仕様ID(`ifx-msg-...`) | ○ |
|
|
59
|
+
| type | `api` 固定 | ○ |
|
|
60
|
+
| rulebook | `specdojo:ifx-msg-rulebook` | ○ |
|
|
61
|
+
| status | ドキュメントメタ情報標準の値 | ○ |
|
|
62
|
+
| based_on | 根拠となる他仕様のIDリスト(例: `["ifx-api-auth"]`) | 任意 |
|
|
70
63
|
|
|
71
64
|
## 5. CloudEventsルール(必須)
|
|
72
65
|
|
|
@@ -79,5 +72,4 @@ CloudEventsの「属性」は仕様で名前が固定です(snake_caseに変
|
|
|
79
72
|
- `time`: 発生時刻(RFC3339)
|
|
80
73
|
- `datacontenttype`: `application/json`
|
|
81
74
|
- `subject`: 任意(推奨。対象を識別できる文字列)
|
|
82
|
-
|
|
83
75
|
- `data`: 業務ペイロード(この中のプロパティ名は snake_case 推奨)
|
|
@@ -13,50 +13,32 @@ specdojo:
|
|
|
13
13
|
|
|
14
14
|
Impact Analysis (Business) Rulebook
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
変更要求による業務への影響を整理し、変更要否・影響度・対応方針・未解決事項を判断するための記述基準を定めます。
|
|
17
17
|
|
|
18
18
|
## 1. 全体方針
|
|
19
19
|
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
- プロセス仕様、データ仕様、テスト仕様への波及がある場合は、本書で概要と判断を記載し、詳細は各ドキュメントへ委譲する。
|
|
20
|
+
- 業務担当者とプロジェクト管理者が合意できる粒度で、業務影響と判断根拠を記載する。
|
|
21
|
+
- 複数領域を扱う場合も影響詳細は業務単位とする。プロセス・データ・テスト仕様への波及は概要と判断を示し、詳細は各仕様へ委ねる。
|
|
22
|
+
- **共通の運用**: 役割は適用先のメンバー定義、`status`・承認・改訂と廃止・未決事項の引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint はリポジトリの検証で扱う。
|
|
24
23
|
|
|
25
|
-
## 2.
|
|
24
|
+
## 2. 位置づけ
|
|
26
25
|
|
|
27
|
-
|
|
28
|
-
| ------------ | ------------------------------------------------------------------ |
|
|
29
|
-
| 変更要求 | プロダクトまたは運用に対する変更の要望。起票済みの要求や課題を含む |
|
|
30
|
-
| 影響対象業務 | 変更要求の影響を受ける業務プロセス、業務ルール、運用手順 |
|
|
31
|
-
| 変更要否 | 影響対象に対して変更が必要かどうかの判定 |
|
|
32
|
-
| 影響度 | 影響の強さ。業務継続性、手戻り、利用者影響を踏まえて評価する |
|
|
33
|
-
| 対応方針 | 影響に対して採用する対処方針(実施、代替、見送りなど) |
|
|
34
|
-
| 未解決事項 | 判断や実施に必要な情報が不足している課題 |
|
|
26
|
+
起票済みの要求・課題を含む変更要求を受け、業務プロセス・ルール・運用手順への影響と対応を判断する。実装設計の詳細化は扱わない。
|
|
35
27
|
|
|
36
28
|
## 3. ファイル命名・ID規則
|
|
37
29
|
|
|
38
30
|
- 対象ドキュメント ID は `<project-id>:imp-business` とする(例: `prj-0001:imp-business`)。
|
|
39
|
-
-
|
|
40
|
-
-
|
|
31
|
+
- 推奨ファイル名は `imp-business.md` とする。
|
|
32
|
+
- 命名の共通規則は [[specdojo:id-and-file-naming-standard|ID・ファイル命名標準]] に従う。
|
|
41
33
|
- 関連する追補文書を分割する場合は `<project-id>:imp-business-<term>` 形式を用いる。
|
|
42
34
|
|
|
43
35
|
## 4. 推奨 Frontmatter 項目
|
|
44
36
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
| 項目 | 説明 | 必須 |
|
|
48
|
-
| ---------- | -------------------------------------------------- | ---- |
|
|
49
|
-
| id | ドキュメント ID(例: `<project-id>:imp-business`) | ○ |
|
|
50
|
-
| type | `project` | ○ |
|
|
51
|
-
| status | `draft` / `ready` / `deprecated` | ○ |
|
|
52
|
-
| rulebook | `specdojo:imp-business-rulebook` 固定 | ○ |
|
|
53
|
-
| part_of | 一覧/親ドキュメントへの所属 ID 配列 | 任意 |
|
|
54
|
-
| based_on | 変更要求や根拠資料の ID 配列 | 任意 |
|
|
55
|
-
| supersedes | 置き換え対象ドキュメント ID 配列 | 任意 |
|
|
37
|
+
共通項目・必須性・型制約は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。`type` は `project`、`rulebook` は `specdojo:imp-business-rulebook` とする。
|
|
56
38
|
|
|
57
39
|
## 5. 本文構成(標準テンプレ)
|
|
58
40
|
|
|
59
|
-
|
|
41
|
+
本文は次の6章を標準とする。
|
|
60
42
|
|
|
61
43
|
| 章 | 見出し | 必須 | 目的 |
|
|
62
44
|
| --- | -------------- | ---- | -------------------------------------------- |
|
|
@@ -76,43 +58,38 @@ Impact Analysis (Business) Rulebook
|
|
|
76
58
|
|
|
77
59
|
### 6.2. 変更要求の概要
|
|
78
60
|
|
|
79
|
-
-
|
|
80
|
-
- 要求詳細は原文を転記せず、判断に必要な要点のみを要約する。
|
|
61
|
+
- 変更の背景・狙い・成功条件を示す。要求詳細は判断に必要な要点に絞る。
|
|
81
62
|
|
|
82
63
|
### 6.3. 影響分析サマリ
|
|
83
64
|
|
|
84
|
-
-
|
|
85
|
-
-
|
|
65
|
+
- 業務継続性、利用者影響、手戻りなどの評価観点と、高・中・低を分ける条件を先に定義する。複数観点で判定が分かれる場合の集約方法も示す。
|
|
66
|
+
- 尺度の例: 高=代替不能な業務停止、中=代替可能だが手順変更が必要、低=現行手順で継続可能。案件に合わせて条件を具体化する。
|
|
67
|
+
- 定義した尺度で件数を集計し、優先対応対象を明記する。
|
|
86
68
|
|
|
87
69
|
### 6.4. 影響詳細一覧
|
|
88
70
|
|
|
89
|
-
-
|
|
71
|
+
- 影響詳細は表形式で、次の6列を必須とする。
|
|
90
72
|
|
|
91
73
|
| カラム | 内容 |
|
|
92
74
|
| ------------ | ------------------------------------ |
|
|
93
75
|
| 影響対象業務 | 影響を受ける業務名または業務プロセス |
|
|
94
76
|
| 変更要否 | `要` / `否` |
|
|
95
|
-
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
| 備考 | 制約、前提、関連ドキュメント |
|
|
77
|
+
| 影響度 | `高` / `中` / `低` |
|
|
78
|
+
| 対応方針 | 実施・代替・見送りなどの方針 |
|
|
79
|
+
| 判断根拠 | 判定理由の要点 |
|
|
80
|
+
| 備考 | 制約、前提、関連ドキュメント |
|
|
100
81
|
|
|
101
82
|
### 6.5. 対応方針
|
|
102
83
|
|
|
103
|
-
-
|
|
84
|
+
- 影響度が高い項目から順に、実施時期、担当、前提条件を記載する。
|
|
104
85
|
- 見送りの場合は、再評価条件と時期を必ず記載する。
|
|
105
86
|
|
|
106
87
|
### 6.6. 未解決事項
|
|
107
88
|
|
|
108
|
-
-
|
|
109
|
-
- 未解決事項は放置せず、次回レビューでの処理方針を記録する。
|
|
89
|
+
- 論点、不足情報、判断・対応への影響と当面の扱いを記載する。未解決事項がなければ「なし」とする。
|
|
110
90
|
|
|
111
91
|
## 7. 禁止事項
|
|
112
92
|
|
|
113
93
|
- 実装詳細(SQL 全文、クラス名、API リクエスト構造)を記載しない。
|
|
114
94
|
- 「影響あり」「要対応」のみで根拠を記載しない。
|
|
115
|
-
|
|
116
95
|
- 影響度の尺度を定義せずに高・中・低を混在させない。
|
|
117
|
-
- 未解決事項に期限や担当を設定せずに放置しない。
|
|
118
|
-
- 他ドキュメントの本文を重複転記し、参照元との不整合を生む記述をしない。
|