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
|
@@ -17,65 +17,64 @@ specdojo:
|
|
|
17
17
|
|
|
18
18
|
Glossary Documentation Rules
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
業務分析・要求定義・設計・テストで使う概念の意味と境界を YAML で定めます。
|
|
21
21
|
|
|
22
22
|
## 1. 全体方針
|
|
23
23
|
|
|
24
|
-
-
|
|
25
|
-
- 定義は `locale`
|
|
26
|
-
-
|
|
27
|
-
-
|
|
24
|
+
- 業務の概念と、利用者が扱う操作・状態・役割を収録する。
|
|
25
|
+
- 定義は `locale` の言語で書く。英語名・コマンド名・固有名詞は併記可。翻訳版は別ファイルにする。
|
|
26
|
+
- 横断の概念は `gl-common`(対象付きなら `gl-<対象>-common`)へ集める。翻訳版を除き、同じ概念を複数の用語集に定義しない。
|
|
27
|
+
- **共通の運用**: 役割は適用先のメンバー定義、`status` の昇格・承認、改訂と廃止、未決事項の引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。整形・lint はリポジトリの検証で扱い、業務の検証に含めない。
|
|
28
28
|
|
|
29
29
|
## 2. 位置づけ
|
|
30
30
|
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
-
|
|
31
|
+
- 意味の正本とし、判定条件・データ項目・操作手順・実装詳細は各仕様・設計へ委ねる。
|
|
32
|
+
- 冒頭のコメントまたは代表用語の注記で、対象範囲と共通・他領域の正本を示す。
|
|
33
|
+
- 配置は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] に従う。
|
|
34
34
|
|
|
35
35
|
## 3. ファイル命名・ID規則
|
|
36
36
|
|
|
37
37
|
### 3.1. ファイル命名
|
|
38
38
|
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
39
|
+
- 基本は `gl-<対象領域>.yaml`(例: `gl-sales.yaml`)。
|
|
40
|
+
- 翻訳版の併置は `gl-<対象領域>-<locale>.yaml` とし、用語集 ID も区別する。
|
|
41
|
+
- 同梱の完成例は `gl-sample.yaml` とする。
|
|
42
42
|
|
|
43
43
|
### 3.2. ID規約
|
|
44
44
|
|
|
45
|
-
- 用語集 ID は
|
|
46
|
-
- 用語 ID は `^tm-[a-z0-9-]
|
|
47
|
-
-
|
|
45
|
+
- 用語集 ID は `^([a-z0-9-]+:)?gl-[a-z0-9-]+$`(完成例は `specdojo:gl-sample`)。
|
|
46
|
+
- 用語 ID は `^tm-[a-z0-9-]+$`。新規は `tm-<領域>-<概念>` とし、共通には `common` など共有範囲を使う。
|
|
47
|
+
- 参照前に採番し、同一プロジェクトの用語集をまたいで一意にする。確定・参照済み ID は接頭辞がなくても維持する。
|
|
48
|
+
- 翻訳版の新規 ID は原語 ID に小文字の言語接尾辞(例: `-en`)を付ける。`source` に原語の用語集リンク・用語 ID を示す。
|
|
48
49
|
|
|
49
50
|
## 4. 推奨 Frontmatter 項目
|
|
50
51
|
|
|
51
|
-
|
|
52
|
+
メタ情報はルートに置く。下記 schema を正本とし、先頭の modeline に相対パスで指定する。
|
|
52
53
|
|
|
53
54
|
| 項目 | 説明 | 必須 |
|
|
54
55
|
| ---------- | -------------------------------------------- | ---- |
|
|
55
56
|
| `id` | 「ID規約」に従う用語集 ID | ○ |
|
|
56
57
|
| `type` | `glossary` 固定 | ○ |
|
|
57
58
|
| `rulebook` | `specdojo:gl-rulebook` | ○ |
|
|
58
|
-
| `title` |
|
|
59
|
+
| `title` | 対象領域を示す用語集名 | ○ |
|
|
59
60
|
| `locale` | 定義の言語(例: `ja` / `en`) | ○ |
|
|
60
61
|
| `status` | 文書成熟度。`draft` / `ready` / `deprecated` | ○ |
|
|
61
62
|
|
|
62
|
-
`
|
|
63
|
+
構造検査は `npm run validate:schema:file -- --schema docs/specdojo/schemas/v1/gl.schema.yaml --data <対象.yaml>`、参照検査は `node packages/docs-lint/bin/specdojo-docs-lint.js glossary-references <対象.yaml>`。ともにエラーなし・終了コード 0 を確認する。modeline は `# yaml-language-server: $schema=<相対パス>`。
|
|
63
64
|
|
|
64
65
|
## 5. 本文要件
|
|
65
66
|
|
|
66
67
|
### 5.1. ルートキー要件
|
|
67
68
|
|
|
68
|
-
-
|
|
69
|
-
-
|
|
70
|
-
- schema
|
|
69
|
+
- ルートの `terms` は必須の用語オブジェクト配列とする。
|
|
70
|
+
- 分類や参照先の概念にも定義を持たせる。
|
|
71
|
+
- schema にないキーは追加しない。
|
|
71
72
|
|
|
72
73
|
### 5.2. `terms` の項目
|
|
73
74
|
|
|
74
|
-
各用語の要素は以下のキーを持つ。
|
|
75
|
-
|
|
76
75
|
| 項目 | 説明 | 必須 |
|
|
77
76
|
| -------------- | ------------------------------------------------------- | ---- |
|
|
78
|
-
| `id` |
|
|
77
|
+
| `id` | 安定した用語 ID | ○ |
|
|
79
78
|
| `term` | 利用者が目にする正式な呼び方 | ○ |
|
|
80
79
|
| `englishName` | 概念の英語名 | 任意 |
|
|
81
80
|
| `aliases` | 同じ概念の別名・従来表記の配列 | 任意 |
|
|
@@ -83,75 +82,66 @@ YAML のメタ情報は `specdojo:` で包まずルートに置く。構造と
|
|
|
83
82
|
| `notes` | 読み手向けの前提・例外・使用文脈 | 任意 |
|
|
84
83
|
| `category` | 同じ用語集内で分類に使う用語 ID | 任意 |
|
|
85
84
|
| `relatedTerms` | 同じ用語集内の関連用語 ID の配列 | 任意 |
|
|
86
|
-
| `source` |
|
|
85
|
+
| `source` | 文書リンク・schema のパスと定義名・URL | 任意 |
|
|
87
86
|
| `status` | 用語の採用状態。`official` / `deprecated` / `candidate` | 任意 |
|
|
88
87
|
| `example` | 用語を使う短い例文 | 任意 |
|
|
89
88
|
|
|
90
|
-
|
|
89
|
+
任意項目は必要なものだけ記載し、用語の `status` と文書成熟度を区別する。`candidate` は業務の利用者・確認者と用例・根拠を照合し、意味・境界・呼び方の合意後に `official` にする。未合意なら候補に留め、`notes` に論点と利用への影響を示す。
|
|
91
90
|
|
|
92
91
|
## 6. 記述ガイド
|
|
93
92
|
|
|
94
93
|
### 6.1. 全体方針・位置づけの判断
|
|
95
94
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
- 良い例: 販売と在庫の両方で使う「商品」は共通へ置き、販売固有の「つけ残高」は販売へ置く。
|
|
99
|
-
- 悪い例: 販売と在庫に同じ「商品」をそれぞれ定義し、更新時にどちらを直すか決まらない。
|
|
95
|
+
- 良い例: 「商品」は共通、「つけ残高」は販売へ置く。
|
|
96
|
+
- 悪い例: 販売と在庫で同じ「商品」を別々に定義する。
|
|
100
97
|
|
|
101
98
|
### 6.2. ファイル命名・ID の判断
|
|
102
99
|
|
|
103
|
-
新規 ID
|
|
100
|
+
新規 ID は名詞を基本とし、難解な略語は避ける。
|
|
104
101
|
|
|
105
|
-
- 良い例:
|
|
106
|
-
- 悪い例: 領域ごとに `tm-status`
|
|
102
|
+
- 良い例: 新規は `tm-sales-credit-limit`、既存の `tm-accounts-receivable` は維持する。
|
|
103
|
+
- 悪い例: 領域ごとに `tm-status` を新設する、整形で確定 ID を改名する。
|
|
107
104
|
|
|
108
105
|
### 6.3. メタ情報・ルート構造の判断
|
|
109
106
|
|
|
110
|
-
`title
|
|
111
|
-
|
|
112
|
-
- 良い例: `title: 用語集(販売)`、`locale: ja` とルートの `terms` を持つ。
|
|
113
|
-
- 悪い例: 全メタ情報を `specdojo:` の下に入れる、または `terms` を文章で代用する。
|
|
107
|
+
- 良い例: `title: 用語集(販売)`、`locale: ja` とルートの `terms`。
|
|
108
|
+
- 悪い例: `specdojo:` で全体を包む、`terms` を文章で代用する。
|
|
114
109
|
|
|
115
110
|
### 6.4. 用語の見出し・英語名の判断
|
|
116
111
|
|
|
117
|
-
`term`
|
|
112
|
+
`term` はガイド・画面・CLI での呼び方に合わせ、言い換えや過去の表記は `aliases` に置く。英語の見出しと `englishName` は小文字とし、大文字が定着した概念名(Kata)と固有名詞(SpecDojo)は例外とする。
|
|
118
113
|
|
|
119
|
-
- 良い例: `term: つけ`、`englishName: sale on credit`、`aliases: [ツケ, 掛け売り]
|
|
120
|
-
- 悪い例:
|
|
114
|
+
- 良い例: `term: つけ`、`englishName: sale on credit`、`aliases: [ツケ, 掛け売り]`。
|
|
115
|
+
- 悪い例: 「つけ」を `term: 売掛債権取引`、英語名を `Sale On Credit` とする。
|
|
121
116
|
|
|
122
117
|
### 6.5. 定義・注記・根拠の判断
|
|
123
118
|
|
|
124
|
-
`definition`
|
|
119
|
+
`definition` は一文を基本とする。`notes` は定義を繰り返さない。設定・コマンドとの対応は理解に必要な範囲に絞り、独立した概念は分ける。
|
|
125
120
|
|
|
126
|
-
- 良い例:
|
|
127
|
-
- 悪い例:
|
|
128
|
-
- schema
|
|
129
|
-
- 良い例:
|
|
130
|
-
- 悪い例:
|
|
131
|
-
- 未確定の内容には共通ラベル(`_TODO_` / `_UNDECIDED_` / `_ASSUMPTION_`)を使い、確定時には解消する。
|
|
121
|
+
- 良い例: つけの注記は「店主が認めた常連客だけが利用する。」とし、残高・限度額は別の用語にする。
|
|
122
|
+
- 悪い例: 定義を「つけとはツケのこと。」で済ませる。
|
|
123
|
+
- schema の条件付き規則は用語間の関係で短く説明し、厳密な条件は `source` へ委ねる。
|
|
124
|
+
- 良い例: 「つけは常連客に認める後払いの販売で、つけ残高を管理する。」
|
|
125
|
+
- 悪い例: schema の `if` / `then` と必須キー一覧を注記へ写す。
|
|
132
126
|
|
|
133
127
|
### 6.6. 分類・関連用語の判断
|
|
134
128
|
|
|
135
|
-
|
|
129
|
+
`category`・`relatedTerms` は同じ用語集の ID に限り、関連語は同じ文脈で理解すべきものに絞る。領域外の関係は `notes` または `source` に正本リンクと必要な用語 ID を示す。
|
|
136
130
|
|
|
137
|
-
- 良い例:
|
|
138
|
-
- 悪い例:
|
|
139
|
-
-
|
|
140
|
-
- 良い例: 共通用語が別ファイルなら「商品の定義は共通用語集を参照する」と文書リンクで案内する。
|
|
141
|
-
- 悪い例: 別ファイルにしかない `tm-common-product` を `relatedTerms` に指定する。
|
|
142
|
-
- `validate:schema` はファイル内の用語 ID の重複と参照先の存在を検証する。用語集をまたぐ ID の一意性と同じ概念の重複定義は、別途横断で照合する。
|
|
131
|
+
- 良い例: 同じファイルの「販売」を分類に使い、別ファイルの「商品」は文書リンクで案内する。
|
|
132
|
+
- 悪い例: 未定義の分類名や別ファイルの ID を指定する、分類のためだけに共通用語を複製する。
|
|
133
|
+
- 参照検査が扱うのはファイル内の ID 重複と参照先の存在だけで、BDD・BR の参照は検査しない。業務の受入確認では用語集を横断して ID の一意性・翻訳以外の概念重複を照合し、参照元で意味と呼び方が一致すれば合格とする。
|
|
143
134
|
|
|
144
135
|
### 6.7. 改訂・廃止時の判断
|
|
145
136
|
|
|
146
|
-
|
|
137
|
+
ID・意味・採用状態の変更影響は、BDD・BR の用語参照、画面・CLI、実装、テスト・受入条件、表示ページで照合する。表示ページは YAML から `specdojo build --only yaml-pages` で再生成し、定義・分類・関連用語の一致を確認する。
|
|
147
138
|
|
|
148
|
-
- 良い例:
|
|
149
|
-
- 悪い例: 旧 ID
|
|
139
|
+
- 良い例: 意味が変わる語は新 ID とし、旧用語は `status: deprecated` と後継の注記を持ち、参照元を更新する。
|
|
140
|
+
- 悪い例: 旧 ID を別の意味に上書きする、参照元を確認せず削除する。
|
|
150
141
|
|
|
151
142
|
## 7. 禁止事項
|
|
152
143
|
|
|
153
|
-
- 用語 ID
|
|
154
|
-
-
|
|
155
|
-
-
|
|
156
|
-
-
|
|
157
|
-
- 読み手向けの意味を補わない編集手順・YAML 記法のメモを `notes` に書くこと。
|
|
144
|
+
- 用語 ID の未採番・重複・意味の異なる語への再利用・確定後の改名。
|
|
145
|
+
- 意味を識別できない定義(「いい感じの在庫」など)。
|
|
146
|
+
- 別名を別概念として定義すること、翻訳以外で領域間に同じ概念を複製すること。
|
|
147
|
+
- 概念の説明を実装詳細・条件一覧で代用すること、編集手順・YAML 記法を `notes` に書くこと。
|
|
@@ -16,100 +16,93 @@ specdojo:
|
|
|
16
16
|
|
|
17
17
|
Infrastructure Flow Diagram (IFD) Documentation Rules using Mermaid
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
実行環境・ネットワーク・信頼境界と主要な通信経路を合意するための規約を定める。
|
|
20
20
|
|
|
21
21
|
## 1. 全体方針
|
|
22
22
|
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
- CIDR、IP、ポート、台数、版、認証値、FW・IAM
|
|
23
|
+
- 上位の要素を実行場所へ対応付け、配置の事実・仮定・未決事項を区別する。
|
|
24
|
+
- 同じホスト上でも管理主体・到達範囲が異なる境界は区別する。
|
|
25
|
+
- 通信は障害の影響範囲と検証対象を識別できる粒度で示す。
|
|
26
|
+
- CIDR、IP、ポート、台数、版、認証値、FW・IAM 設定、コマンド構文は載せず、技術構成・連携・運用の正本へ委ねる。
|
|
27
|
+
- 共通の運用: 役割の割り当ては適用先のメンバー定義に、`status` の昇格と承認、改訂と廃止、未決事項の引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint はリポジトリの検証で扱い、成果物の検証観点に含めない。
|
|
27
28
|
|
|
28
29
|
## 2. 位置づけと用語定義
|
|
29
30
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
|
|
|
34
|
-
|
|
|
35
|
-
| 上位構成図 | 処理・データ・外部依存の責務を定義する入力。論理的なコンテナと実行用コンテナを同一視しない |
|
|
36
|
-
| 詳細設計・運用文書 | 接続設定、認証方式、監視閾値、復旧手順を管理する委譲先 |
|
|
31
|
+
| 用語 | 本書での意味 |
|
|
32
|
+
| ---------------- | ------------------------------------------------------------------ |
|
|
33
|
+
| ネットワーク境界 | 到達経路・接続条件が変わる区切り。物理構成と一致するとは限らない |
|
|
34
|
+
| 論理ゾーン | 管理主体、公開範囲、情報の持ち出し条件を検討する区切り |
|
|
35
|
+
| 上位構成図 | 責務を定義する入力。論理的なコンテナと実行用コンテナを同一視しない |
|
|
37
36
|
|
|
38
37
|
## 3. ファイル命名・ID規則
|
|
39
38
|
|
|
40
|
-
- ファイル名は `ifd-<target>.md`
|
|
41
|
-
-
|
|
42
|
-
- Mermaid のノード ID と表示名を分離する。文書内で一意な ID を使い、改訂時も同じ要素・経路の ID を維持する。
|
|
39
|
+
- ファイル名は `ifd-<target>.md` とし、`id` は stem と対応させる。共通規則は [[specdojo:docs-structure-guide|ドキュメント構造ガイド]] を正とする。
|
|
40
|
+
- Mermaid のノード ID と表示名を分離し、改訂時も同じ要素・経路の ID を維持する。
|
|
43
41
|
|
|
44
42
|
## 4. 推奨 Frontmatter 項目
|
|
45
43
|
|
|
46
|
-
共通の値・構文は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]]
|
|
44
|
+
共通の値・構文は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] を正とする。
|
|
47
45
|
|
|
48
46
|
| 項目 | 扱い | IFD での用途 |
|
|
49
47
|
| ------------------------ | -------- | ---------------------------------------------------- |
|
|
50
|
-
| `id` / `type` / `status` | 必須 | 文書の識別、`architecture` 分類、成熟度 |
|
|
51
48
|
| `rulebook` | 必須 | `specdojo:ifd-mermaid-rulebook` を指定する |
|
|
52
|
-
| `owner` | 推奨 | 配置・境界設計を担うロール |
|
|
53
49
|
| `based_on` | 条件付き | 直接の根拠となる上位構成図。単なる参考文書は含めない |
|
|
54
50
|
| `part_of` / `supersedes` | 条件付き | 所属・置き換え関係がある場合に記載する |
|
|
55
51
|
|
|
56
52
|
## 5. 本文要件
|
|
57
53
|
|
|
58
|
-
|
|
54
|
+
骨組みは template を正本とし、以下は内容の成立条件である。
|
|
59
55
|
|
|
60
|
-
| 内容 | 必須性 |
|
|
61
|
-
| ------------------------ | -------- |
|
|
62
|
-
| 概要 | 必須 | 対象環境、図で判断すること、上位入力、対象外を識別できる
|
|
63
|
-
| インフラ構成図 | 必須 | 実行場所、必要な境界、主要経路を Mermaid で示し、凡例で向き・線種・省略を説明する
|
|
64
|
-
| 配置と境界の定義 | 必須 |
|
|
65
|
-
| 通信経路と情報の境界 | 必須 | 図と本文の経路 ID
|
|
66
|
-
| 技術前提・制約と検証観点 | 必須 |
|
|
67
|
-
| メモ / 将来課題 | 条件付き |
|
|
56
|
+
| 内容 | 必須性 | 判定条件 |
|
|
57
|
+
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
|
|
58
|
+
| 概要 | 必須 | 対象環境、図で判断すること、上位入力、対象外を識別できる |
|
|
59
|
+
| インフラ構成図 | 必須 | 実行場所、必要な境界、主要経路を Mermaid で示し、凡例で向き・線種・省略を説明する |
|
|
60
|
+
| 配置と境界の定義 | 必須 | 要素に管理主体・保持情報・到達条件を対応付け、上位要素の配置か対象外かを示す。代替配置は適用条件を示す |
|
|
61
|
+
| 通信経路と情報の境界 | 必須 | 図と本文の経路 ID・起点・終点が対応し、目的、情報の要点、利用条件、詳細の正本を追える |
|
|
62
|
+
| 技術前提・制約と検証観点 | 必須 | 隔離・認証・公開の前提と、境界別の障害影響・観測対象を示す |
|
|
63
|
+
| メモ / 将来課題 | 条件付き | 仮定・未決事項がある場合、論点と影響(当面の扱い)を残す |
|
|
68
64
|
|
|
69
65
|
### 5.1. Mermaid の表現規約
|
|
70
66
|
|
|
71
|
-
- `flowchart LR`
|
|
72
|
-
- `subgraph` は最大 3
|
|
73
|
-
-
|
|
74
|
-
- 処理は矩形、DB
|
|
75
|
-
- 経路ラベルに ID
|
|
76
|
-
-
|
|
77
|
-
-
|
|
67
|
+
- `flowchart LR` を使う。矢印は主たる起点から終点へ向け、応答は同じ線に含める。独立した逆方向の起動だけを別線にする。
|
|
68
|
+
- `subgraph` は最大 3 階層とし、必要な境界だけを描いて各枠が何の区切りか明記する。
|
|
69
|
+
- 表示名は役割を主語とし、製品名は「推論サービス(製品名)」のように補記する。
|
|
70
|
+
- 処理は矩形、DB は円筒、ファイル保管は角丸を基本とし、形状・色・絵文字だけに意味を持たせない。
|
|
71
|
+
- 経路ラベルに ID と通信目的を付け、プロトコル名だけにしない。線種を分ける場合は凡例で定義する。
|
|
72
|
+
- 中継を省略して一本で描く場合は、図の近傍で中継と到達条件を説明し、直接接続と誤読させない。
|
|
73
|
+
- 色は `classDef` で役割の分類を統一する。交差が判断を妨げる場合は範囲を分割し、共有要素と経路 ID を対応付ける。
|
|
74
|
+
- 図の確認: 「インフラ構成図」章の全 Mermaid ブロックの構文を `npm run lint:mermaid` で確かめ、描画プレビューで表示名・経路ラベル・枠名が読めること、枠の包含が「配置と境界の定義」と一致することを確かめる。
|
|
78
75
|
|
|
79
76
|
## 6. 記述ガイド
|
|
80
77
|
|
|
81
|
-
共通のメタ情報・リンク記法は上位標準を正本とし、本章では IFD 固有の判断だけを扱う。
|
|
82
|
-
|
|
83
78
|
### 6.1. 概要
|
|
84
79
|
|
|
85
|
-
|
|
80
|
+
対象環境と判断範囲を先に選ぶ。良い例は「店舗端末から共有サービスまでの到達範囲を示し、通信不能時の切り分けに使う」。悪い例は「システム全体を説明する」。
|
|
86
81
|
|
|
87
82
|
### 6.2. インフラ構成図
|
|
88
83
|
|
|
89
|
-
|
|
84
|
+
枠を越えるごとに実行場所・接続条件・管理主体のどれが変わるかで描き分ける。良い例は「店舗端末と外部保管サービスを別枠にし、送信する記録をラベルにする」。悪い例は「同じ製品なので外部サービスも端末の枠に入れる」。
|
|
90
85
|
|
|
91
86
|
### 6.3. 配置と境界の定義
|
|
92
87
|
|
|
93
|
-
|
|
88
|
+
図にない管理責務・保持情報を補う。推奨列は「図中の環境・要素、上位要素、管理主体、情報・到達条件」。良い例は「作業記録は端末側、外部には送信対象だけを渡す案」。悪い例は「Private 枠なので安全」。
|
|
94
89
|
|
|
95
|
-
|
|
90
|
+
代替配置が選択肢なら、置き換え後の保持範囲・到達性を確認対象にする。良い例は「ホストで同じ役割を実行し、書込範囲を再確認する」。悪い例は「両環境に同名の処理を置き、稼働条件を示さない」。
|
|
96
91
|
|
|
97
92
|
### 6.4. 通信経路と情報の境界
|
|
98
93
|
|
|
99
|
-
条件付きの外部依存を常時必須の経路と混ぜない。推奨列は「経路 ID、起点 →
|
|
94
|
+
条件付きの外部依存を常時必須の経路と混ぜない。推奨列は「経路 ID、起点 → 終点、目的・情報、利用条件・詳細の委譲先」。良い例は「共有時だけ控えを外部へ送り、接続・認証の契約は連携仕様で定める」。悪い例は「全データを同期する」。
|
|
100
95
|
|
|
101
96
|
### 6.5. 技術前提・制約と検証観点
|
|
102
97
|
|
|
103
|
-
|
|
98
|
+
境界が成立する条件と、崩れたときに観測するものを結ぶ。良い例は「別ホストへの到達不能、応答欠落、保存失敗を分けて観測する」。悪い例は「トンネルがつながるので作業も成功する」。検証設計への入力と実施済みの証跡を区別し、閾値や復旧コマンドを再定義しない。
|
|
104
99
|
|
|
105
100
|
### 6.6. メモ / 将来課題
|
|
106
101
|
|
|
107
|
-
|
|
102
|
+
不明点が配置・境界・経路のどこに効くかで影響を具体化する。良い例は「公開先が未決のため公開経路は仮定とし、決まったら枠と経路を直す」。悪い例は「後で検討する」。
|
|
108
103
|
|
|
109
104
|
## 7. 禁止事項
|
|
110
105
|
|
|
111
106
|
- 上位図の責務を変更したり、業務判断・公開可否・製品採択を根拠なく確定したりしない。
|
|
112
107
|
- 論理ゾーンやトンネルの存在だけから、隔離・認証・情報非保持を保証しない。
|
|
113
108
|
- 詳細設定・schema・リファレンスの値、構文、構造を複製しない。秘密値や個人固有の接続先を載せない。
|
|
114
|
-
- 完成図の例を本書に埋め込まない。対応する型の所在は frontmatter の宣言で管理する。
|
|
115
|
-
- 改訂・廃止で経路や境界が変わる場合、追従先を省略しない。ARC が上位構成図・連携設計、QE が検証対象、OPS が監視・運用参照、PO が公開判断への影響を確認する。ライフサイクル手続きは共通メタ情報標準に従う。
|
|
@@ -14,23 +14,22 @@ specdojo:
|
|
|
14
14
|
|
|
15
15
|
外部システム(仕入先、会計、物流、決済など)と連携する **1つのREST APIインターフェース**を、**OpenAPI形式**(YAML 1ファイル)で定義します。
|
|
16
16
|
|
|
17
|
-
EAPIS は ESIL(外部システムIF
|
|
18
|
-
|
|
17
|
+
EAPIS は ESIL(外部システムIF一覧)から参照される「詳細仕様」で、ESIL 側の `spec_ref: ifx-api-...` をこの EAPIS の ID とファイル名に対応させます。
|
|
18
|
+
|
|
19
|
+
`status` の昇格と承認、改訂と廃止は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従い、本書では言い直しません。
|
|
19
20
|
|
|
20
21
|
## 1. ファイル規約
|
|
21
22
|
|
|
22
|
-
- ファイル名: `ifx-api-<短い英小文字ハイフン>.yaml`
|
|
23
|
-
- ESILからの参照: `spec_ref: ifx-api-...`(例: `ifx-api-payment`)
|
|
23
|
+
- ファイル名: `ifx-api-<短い英小文字ハイフン>.yaml`(例: `ifx-api-payment`)
|
|
24
24
|
- 1ファイル = 1つのAPI(1つの外部連携インターフェース)
|
|
25
25
|
|
|
26
26
|
## 2. OpenAPIバージョン
|
|
27
27
|
|
|
28
|
-
- **OpenAPI 3.0.3
|
|
29
|
-
- 本リポジトリでは互換性のため **3.0.3** を第一候補とする
|
|
28
|
+
- 互換性のため **OpenAPI 3.0.3** を第一候補とし、**3.1.x** も使えます。
|
|
30
29
|
|
|
31
30
|
## 3. 記載方針(必須)
|
|
32
31
|
|
|
33
|
-
-
|
|
32
|
+
- **外部との合意に必要な最小十分**を記載する
|
|
34
33
|
- `paths` は **実際に提供/利用するエンドポイントのみ**定義する
|
|
35
34
|
- `operationId` は英字で一意にする(例: `createPayment`)
|
|
36
35
|
- スキーマは `components/schemas` に集約し、`$ref` で参照して使い回す
|
|
@@ -54,22 +53,19 @@ ESIL 側の `spec_ref: ifx-api-...` は、このEAPISのID(およびファイ
|
|
|
54
53
|
- `servers`(少なくとも1つ)
|
|
55
54
|
- `paths`(少なくとも1つ)
|
|
56
55
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
仕様のトレーサビリティ管理のため、以下を `x-spec-meta` に含めます。
|
|
56
|
+
### 4.1. メタ情報(x-spec-meta)
|
|
60
57
|
|
|
61
|
-
| キー
|
|
62
|
-
|
|
|
63
|
-
|
|
64
|
-
|
|
|
65
|
-
|
|
|
66
|
-
|
|
|
67
|
-
| status | `draft` / `ready` / `deprecated` | ○ |
|
|
58
|
+
| キー | 説明 | 必須 |
|
|
59
|
+
| -------- | ---------------------------------------------------- | ---- |
|
|
60
|
+
| id | API仕様ID(`ifx-api-...`) | ○ |
|
|
61
|
+
| type | `api` 固定 | ○ |
|
|
62
|
+
| rulebook | `specdojo:ifx-api-rulebook` | ○ |
|
|
63
|
+
| status | ドキュメントメタ情報標準の値 | ○ |
|
|
68
64
|
| based_on | 根拠となる他仕様のIDリスト(例: `["ifx-api-auth"]`) | 任意 |
|
|
69
65
|
|
|
70
66
|
## 5. エラー定義(推奨)
|
|
71
67
|
|
|
72
|
-
|
|
68
|
+
外部連携では、少なくとも以下のエラーレスポンスを定義し、共通形式(例: `components/schemas/ErrorResponse`)を各 operation から参照します。
|
|
73
69
|
|
|
74
70
|
- `400`(入力不正)
|
|
75
71
|
- `401`(認証)/ `403`(認可)
|
|
@@ -77,5 +73,3 @@ ESIL 側の `spec_ref: ifx-api-...` は、このEAPISのID(およびファイ
|
|
|
77
73
|
- `409`(競合)
|
|
78
74
|
- `429`(レート制限)
|
|
79
75
|
- `500`(内部エラー)
|
|
80
|
-
|
|
81
|
-
共通形式(例: `components/schemas/ErrorResponse`)を用意し、各operationから参照する運用を推奨します。
|
|
@@ -14,21 +14,19 @@ specdojo:
|
|
|
14
14
|
|
|
15
15
|
External Command Interface Specification (ECIS) Documentation Rules
|
|
16
16
|
|
|
17
|
-
外部 CLI
|
|
17
|
+
外部 CLI プロセスとの実行契約、入出力、終了判定、副作用、失敗処置、認証注入を YAML 1 ファイルで定義する基準を定めます。
|
|
18
18
|
|
|
19
19
|
## 1. 全体方針
|
|
20
20
|
|
|
21
|
-
- **1 連携 1 ファイル**:
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
- **秘密値を持たない**: 認証は注入方式・参照名・管理境界で表す。秘密値を本文、入力例、出力例、ログに含めない。
|
|
21
|
+
- **1 連携 1 ファイル**: 実行目的と入出力契約を単位とし、同じ CLI でも目的・権限・出力契約が異なれば分割する。複数 provider をまとめる場合は、共通契約と差異の正本を示す。
|
|
22
|
+
- **正本を分担する**: 共通事項は上位の外部 I/F 一覧・設計、構造・値の制約は schema、起動方法は設定・リファレンスへ委ね、プロセス境界の判断情報に絞る。
|
|
23
|
+
- **起動方式を事実に合わせる**: 原則はシェルを経由しない。例外条件は「コマンドと正本参照」に従う。
|
|
24
|
+
- **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status`・承認・改訂と廃止・未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint・構造検証はリポジトリの検証で扱い、業務の受入確認に含めない。
|
|
26
25
|
|
|
27
26
|
## 2. 位置づけ
|
|
28
27
|
|
|
29
|
-
- ESIL(外部システム I/F
|
|
28
|
+
- ESIL(外部システム I/F 一覧)の `spec_ref` の先でプロセス境界の契約を定める。API・ファイル・メッセージ連携の操作手段として CLI を使う場合は、各方式の仕様を正本とする。
|
|
30
29
|
- 起動方法の正本は対象によって選ぶ。SpecDojo 自身のコマンドはコマンドリファレンス、SpecDojo が起動する AI provider CLI は起動設定の `command_template` と [[specdojo:exec-config-guide|exec 設定ガイド]]、その他の外部 CLI は公式リファレンスや製品マニュアルを参照する。
|
|
31
|
-
- ARC は境界・制約・正本分担、DEV は起動と結果判定の実装可能性、QE は正常・異常・再試行の検証可能性、PO / BA は実行目的と副作用の業務上の妥当性を確認する。
|
|
32
30
|
|
|
33
31
|
## 3. ファイル命名・ID規則
|
|
34
32
|
|
|
@@ -39,15 +37,14 @@ External Command Interface Specification (ECIS) Documentation Rules
|
|
|
39
37
|
|
|
40
38
|
## 4. 先頭メタ項目
|
|
41
39
|
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
-
|
|
45
|
-
- `based_on` には実際に確認した直接の根拠だけを書く。カタログ管理下では `depends_on` の推移閉包内に限定し、起動方法の参照先を示す `command.reference` と役割を混同しない。
|
|
40
|
+
- 先頭メタ項目と雛形自身のメタ情報は、[[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] の「独立 YAML データファイルのメタ情報」と「生成物メタ情報雛形(`metadata_template`)」に従う。
|
|
41
|
+
- 成果物(雛形では `metadata_template` 内)は `type: api`、`rulebook: specdojo:ifx-cmd-rulebook` とし、`title` で対象と実行目的を識別する。
|
|
42
|
+
- `based_on` は作成根拠、`command.reference` は起動方法の正本参照として区別する。
|
|
46
43
|
- メタ項目の `version` は呼び出し契約の改版、`command.version_constraint` は CLI の対応バージョンを表す。
|
|
47
44
|
|
|
48
45
|
## 5. 本文要件
|
|
49
46
|
|
|
50
|
-
|
|
47
|
+
構造・型・許容値は `docs/specdojo/schemas/v1/ifx-cmd.schema.yaml` を正本とする。以下は契約の内容要件であり、schema で任意の項目も、本書で必須とした場合は記述する。
|
|
51
48
|
|
|
52
49
|
| 対象キー | 必須性 | 契約として定める内容 |
|
|
53
50
|
| ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -60,35 +57,35 @@ YAML の構造、入れ子キー、型、列挙値は `docs/specdojo/schemas/v1/
|
|
|
60
57
|
| `execution` | 必須 | 作業ディレクトリ、時間・並列実行・ネットワークの制約、冪等性の成立条件または保証できない理由 |
|
|
61
58
|
| `error_handling` | 必須 | 再試行の対象と上限・待機方式、タイムアウト、出力解析失敗、認証失敗に対する個別の処置 |
|
|
62
59
|
|
|
63
|
-
|
|
60
|
+
`arguments` は既存仕様との後方互換性のための定義である。新規作成・改訂では引数表を持たず、`command.reference` と入出力の契約へ一本化する。
|
|
64
61
|
|
|
65
62
|
## 6. 記述ガイド
|
|
66
63
|
|
|
67
64
|
### 6.1. 連携単位とメタ情報
|
|
68
65
|
|
|
69
|
-
- **判断基準**: ESIL
|
|
70
|
-
-
|
|
66
|
+
- **判断基準**: ESIL の目的と成功後の状態が対応し、1 ファイルを一つの契約として検証できること。provider 一覧や設定値を複数キーへ繰り返さない。
|
|
67
|
+
- **影響の照合先**: ESIL の参照行、呼び出し元の業務完了・回復条件、起動設定・入出力処理、正常・異常・再試行の検証を照合する。
|
|
71
68
|
- **良い例**: 読取と更新を別 ID にし、`title` に対象と目的を書く。provider ごとに実行ファイルが変わるときは、`executable` に設定の該当キーから解決する旨を示し、一覧自体は設定へ委ねる。
|
|
72
69
|
- **悪い例**: 一つの仕様に読取・登録・削除を混在させる。設定の provider 一覧を目的・実行ファイル・コメントへそれぞれ転載する。
|
|
73
70
|
|
|
74
71
|
### 6.2. コマンドと正本参照
|
|
75
72
|
|
|
76
73
|
- **判断基準**: `purpose` で呼び出し元から見た成功後の状態を示し、`reference` で正本の文書・設定キー・対象操作を特定する。通常は実行ファイルとサブコマンドを分け、`shell: false` とする。
|
|
77
|
-
- **シェル起動の例外**:
|
|
74
|
+
- **シェル起動の例外**: 呼び出し元が管理された起動設定を展開し、シェルが必要な場合は `shell: true` を認める。理由、テンプレートの正本と管理境界、展開値の検証・制限の参照先を示す。利用者入力の無制限なシェル構文評価は認めない。テンプレート全文や複数コマンドの処理手順は転載しない。
|
|
78
75
|
- **良い例**: AI provider CLI では `reference` に `.specdojo/exec-defaults.yaml` の `providers.<provider>.command_template` と exec 設定ガイドを示す。`shell: true` の理由を stdin から起動引数への変換として説明し、設定の保護と展開値の検証は同ガイドの契約を参照する。
|
|
79
76
|
- **悪い例**: 実際はシェルを使うのに `false` と書く。「外部 CLI だから」という理由だけで `true` にする。`executable` に引数やパイプを連結し、起動設定と別のコマンド全文を管理する。
|
|
80
77
|
|
|
81
78
|
### 6.3. ストリーム
|
|
82
79
|
|
|
83
|
-
- **判断基準**: stdin
|
|
84
|
-
- **良い例**:
|
|
80
|
+
- **判断基準**: stdin は入力内容と終端、stdout は採用範囲、stderr は診断用途を記す。stdin を使わない場合も要否と形式を明示する。出力の詳細構造は正本へ委ね、判定に必要な意味を残す。
|
|
81
|
+
- **良い例**: 進捗が混在する stdout では、末尾の構造化報告の抽出範囲と欠落・解析失敗時の扱いを示す。終了コードと報告内容の両方で完了を判断するなら、各々が保証する範囲を書く。
|
|
85
82
|
- **悪い例**: 構造化部分があることを理由に stdout 全体を JSON と記す。「CLI の既定出力」とだけ書く。stderr が空なら成功と判定する。
|
|
86
83
|
|
|
87
84
|
### 6.4. ファイル
|
|
88
85
|
|
|
89
|
-
- **判断基準**:
|
|
90
|
-
- **入出力がない場合**:
|
|
91
|
-
- **良い例**:
|
|
86
|
+
- **判断基準**: 入出力別に、パスの基準、可変部の供給元と書式、形式、作成・更新・読取主体、内容仕様の正本を特定する。`description` など既存欄で説明し、専用キーやフィールド一覧を追加しない。CLI の生成物と呼び出し元の実行記録を区別する。
|
|
87
|
+
- **入出力がない場合**: 入出力のない側の配列は `[]` または省略で表し、どちらも該当の入出力がないことを意味する。入出力が一切なければ `files` 自体を省略できる。未確認の場合と混同しない。
|
|
88
|
+
- **良い例**: 入力の相対パス、可変部分の解決元(確定済み取引の識別情報)、作成主体(呼び出し元)、内容仕様の正本を示す。CLI が出力ファイルを作らない例では `outputs: []` とし、呼び出し元のログ保存と分ける。
|
|
92
89
|
- **悪い例**: 出力を「各種ファイル」とだけ書く。呼び出し元が保存するログや別段階で作成する result を、同じ CLI の出力として列挙する。入力ファイルの作成主体や可変部分の解決元が書かれていない。
|
|
93
90
|
|
|
94
91
|
### 6.5. 終了状態と識別条件
|
|
@@ -112,31 +109,22 @@ schema の後方互換性定義として残されている `arguments` の各項
|
|
|
112
109
|
|
|
113
110
|
### 6.8. 実行制約と失敗処置
|
|
114
111
|
|
|
115
|
-
- **判断基準**:
|
|
112
|
+
- **判断基準**: 作業ディレクトリと時間・並列実行・ネットワークの制約は公開契約や確認した実装・設定を根拠にする。schema で参照値や上限なしを表せず判断が未了なら、許容されるプレースホルダと共通ラベルで現在動作・不足する判断・影響・確認先を残し、架空の固定値で埋めない。
|
|
116
113
|
- **再試行と回復**: `retryable` と `retry.on_categories` を照合し、対象条件、試行上限の数え方、待機方式を揃える。利用制限でも短時間の制限と利用枠の枯渇を区別し、実際の停止・待機・切替条件は正本へ委ねる。タイムアウト時の子プロセスと部分出力、出力解析失敗時の既存変更、認証失敗時の確認先を個別に定める。
|
|
117
114
|
- **良い例**: タイムアウトが未決定なら、現在は終了まで待つことと、上限・終了処置を決める必要を区別して記す。出力異常時は自動再試行を止め、変更を保持して人の確認または再開に委ねる。
|
|
118
115
|
- **悪い例**: schema を通すためだけに時間や並列数を捏造する。「失敗時はリトライ」とだけ書く。認証・認可・入力不正を待機だけで回復する一時失敗として扱う。
|
|
119
116
|
|
|
120
117
|
### 6.9. 成果物の検証手順
|
|
121
118
|
|
|
122
|
-
- **判断基準**: 作成・改訂した仕様 YAML
|
|
123
|
-
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
npx prettier --check '<対象YAMLファイルのrepository相対パス>'
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
- **期待結果とエラー時対応**: schema 検証は対象パスに続く `: valid` と終了コード 0、整形確認は差分なしと終了コード 0 を確認する。エラー時は報告されたキー・型・メタ情報や整形差分を修正し、同じ対象で再実行する。
|
|
131
|
-
- **契約内容の照合**: 構造検証では判定できない正本参照の実在・適用範囲、ファイルの作成主体・可変パス・内容仕様、終了判定と回復条件を照合する。DEV は起動・入出力・報告解析の検証入口、QE は正常・異常・再試行の期待結果、BA は業務完了と副作用を確認できるよう、参照先と結果を実行記録に残す。CLI 自体を起動する検証の詳細は参照先へ委ねる。
|
|
132
|
-
- **良い例**: 変更した YAML と対応 schema を指定し、成功表示と終了コードを記録する。そのうえで、終了コードが同じ失敗の識別や再実行時の副作用を正本と照合する。
|
|
133
|
-
- **悪い例**: schema のパスだけを示す。雛形の構造検証を省略したログを完成した仕様の検証成功とする。schema 合格だけで業務完了や再試行の安全性も保証したとみなす。
|
|
119
|
+
- **判断基準**: 作成・改訂した仕様 YAML の契約を、参照する正本と起動・入出力・報告解析の検証入口へ照合できること。CLI を起動する検証の詳細は参照先へ委ねる。
|
|
120
|
+
- **確認手順**: 正本の実在と適用範囲、ファイルの作成主体・可変パス・内容仕様を照合し、正常、同じコードの異なる失敗、出力欠落、途中失敗後の再実行を追う。入力・観測信号・期待結果と検証入口の参照先、確認結果を実行記録に残す。
|
|
121
|
+
- **合格条件**: 各ケースの業務完了判定、次の動作、副作用と回復条件が契約と一致する。識別不能な失敗は自動分類せず手動確認へつながり、未決事項は現在動作と影響をたどれること。不一致は仕様または参照先を修正し、該当ケースを再確認する。
|
|
122
|
+
- **良い例**: 同じ exit 1 を追加信号と判定順で分類し、途中失敗後の再実行で二重処理を防ぐ条件まで正本・検証結果と照合する。
|
|
123
|
+
- **悪い例**: schema 合格だけで業務完了や再試行の安全性も保証したとみなす。検証入口を示さず「動作確認済み」とする。
|
|
134
124
|
|
|
135
125
|
## 7. 禁止事項
|
|
136
126
|
|
|
137
|
-
-
|
|
127
|
+
- 引数表、起動テンプレート全文、検出パターン一覧を正本と別に管理すること。
|
|
138
128
|
- シェル起動の例外条件を満たさず `shell: true` とすること、または実際の起動方式を隠して `false` とすること。
|
|
139
|
-
- 秘密値、秘密値を含む URL、個人の認証パスを本文・例・ログに含めること。
|
|
140
129
|
- stdout / stderr、プロセス終了 / 業務完了、CLI の生成物 / 呼び出し元の記録を混同すること。
|
|
141
130
|
- 追加信号のない終了コードだけで原因を断定したり、副作用の回復条件がないまま自動再試行したりすること。
|
|
142
|
-
- 内部クラス名、プロセス起動ライブラリの API 呼び出し、スクリプト全文など、合意境界に不要な内部実装を記載すること。
|