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
|
@@ -11,96 +11,119 @@ specdojo:
|
|
|
11
11
|
|
|
12
12
|
System Design Critical Flows Authoring Recipe
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
取り返しのつかない境界と失敗後の次の手を見つけ、実装・検証・運用の担当が同じ判断へ戻れる重要フローに仕上げる作り方を示す。
|
|
15
15
|
|
|
16
16
|
## 1. このレシピの使い方
|
|
17
17
|
|
|
18
|
-
-
|
|
19
|
-
- この文書で確定するのは処理の境界、成功を認める保存状態、重複・中断後に許す動作である。
|
|
20
|
-
- How は整合性・排他・保持・再開の方針までとし、設定値や操作の構文は正本へ委ねる。
|
|
21
|
-
- フロー ID、受入条件、検証 ID、未決事項 ID を対応させ、主要な判断を根拠と証跡へ結ぶ。
|
|
18
|
+
- 業務フローから、失敗すると誰の何が損なわれるか(Why)を引き継ぎ、処理の境界・成功を認める保存状態・中断後に許す動作(What)を決め、整合・排他・保持・再開の方針(How)までを書く。フロー ID で受入条件・検証・未決事項を結ぶ(Trace)。
|
|
22
19
|
|
|
23
20
|
## 2. 作成前に集める情報
|
|
24
21
|
|
|
25
|
-
| 集める情報
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
22
|
+
| 項目 | 集める情報 | 取り出し元 |
|
|
23
|
+
| ---------------- | -------------------------------------------- | ---------------------------- |
|
|
24
|
+
| 対象者と損失 | 失敗で誰が何をやり直し、何が残るか | 業務フロー、プロジェクト概要 |
|
|
25
|
+
| 境界と識別子 | 内外の境界と、要求・受付・完了の識別キー | システム設計索引、連携契約 |
|
|
26
|
+
| 状態と権限 | 再実行・取消・承認の意味と、それを判断する人 | 状態遷移仕様、判断記録 |
|
|
27
|
+
| 上限と設定の所在 | 上限と優先順位の正本 | 実装・設定の担当への確認 |
|
|
28
|
+
| 検証と復旧の実績 | 既存のテスト・復旧手順と未整備のもの | テスト担当・運用担当への確認 |
|
|
32
29
|
|
|
33
30
|
## 3. 全体の作成手順
|
|
34
31
|
|
|
35
|
-
1.
|
|
36
|
-
2.
|
|
37
|
-
3.
|
|
38
|
-
4.
|
|
39
|
-
5.
|
|
40
|
-
6.
|
|
32
|
+
1. 概要で入口・出口・対象外を決める。これが事故候補を比べる範囲になる。
|
|
33
|
+
2. 一覧で事故候補を利用者の損失で比べる。候補が多ければ、同じ事故を防ぐ候補をまとめる。
|
|
34
|
+
3. フロー詳細で、成功の確定点を先に置き、そこへ至る処理・保存先・識別子を図にする。確定点が先にないと、図が通常処理の説明になる。
|
|
35
|
+
4. 各保存点の直前・直後で止めた場合の残存状態と次の手を決める。
|
|
36
|
+
5. 観測性と運用連携で、機械が検出する条件と人間が対応する責任を分ける。
|
|
37
|
+
6. 最後に関連ドキュメント導線で、正本への参照と変更の波及をつなぐ。足りない根拠は未決事項にする。
|
|
41
38
|
|
|
42
39
|
## 4. 各章の書き方
|
|
43
40
|
|
|
44
41
|
### 4.1. 概要
|
|
45
42
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
-
|
|
43
|
+
問い:
|
|
44
|
+
|
|
45
|
+
- どの操作からどの業務結果までを扱い、通常処理を外した理由は何か。
|
|
46
|
+
- 公開版に、実行記録や個人を識別できる情報が紛れていないか。
|
|
47
|
+
|
|
48
|
+
コツ:
|
|
49
|
+
|
|
50
|
+
- 状態用語や対象者の説明を写したくなったら、業務フロー・状態遷移仕様への参照に置き換える。
|
|
51
|
+
- 根拠が廃止済みの文書だけなら、現行仕様との照合を未決事項にする。
|
|
49
52
|
|
|
50
53
|
### 4.2. 重要フロー一覧
|
|
51
54
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
-
|
|
55
|
+
問い:
|
|
56
|
+
|
|
57
|
+
- 放置すると誰の何が壊れ、成功すればどの負荷が減るか。
|
|
58
|
+
- その損失は、ほかの候補より重いか。
|
|
59
|
+
|
|
60
|
+
コツ:
|
|
61
|
+
|
|
62
|
+
- 対象者・事故・影響・効果を 1 行で言えない候補は、まだ詳細へ進めない。
|
|
55
63
|
|
|
56
64
|
### 4.3. フロー詳細
|
|
57
65
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
-
|
|
66
|
+
問い:
|
|
67
|
+
|
|
68
|
+
- どの記録が残れば成功と言えるか。
|
|
69
|
+
- 応答を失った後の再送で、二度目の副作用が起きないか。取り消せないなら、何を保持して誰が照合するか。
|
|
70
|
+
|
|
71
|
+
コツ:
|
|
72
|
+
|
|
73
|
+
- 処理主体と保存先を分け、境界を越える要求と応答を同じ識別子で追うと、受付と完了の取り違えが見つかる。
|
|
61
74
|
|
|
62
75
|
### 4.4. 観測性と運用連携
|
|
63
76
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
-
|
|
77
|
+
問い:
|
|
78
|
+
|
|
79
|
+
- 同じ処理を内外でどのキーで照合するか。trace を渡せない境界では何で追うか。
|
|
80
|
+
- 検知の後、誰が何を止め、どこへ相談するか。
|
|
81
|
+
|
|
82
|
+
コツ:
|
|
83
|
+
|
|
84
|
+
- 閾値を使うなら測定元と判定時点を正本に聞く。未決なら未決事項にし、無通知でよいとは書かない。
|
|
67
85
|
|
|
68
86
|
### 4.5. 関連ドキュメント導線
|
|
69
87
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
-
|
|
88
|
+
問い:
|
|
89
|
+
|
|
90
|
+
- どの設定とテスト・復旧手順を読めば、成功条件を再現できるか。
|
|
91
|
+
- フローの変更で、契約・保存済みの記録・CLI のどれに影響が及ぶか。
|
|
92
|
+
|
|
93
|
+
コツ:
|
|
94
|
+
|
|
95
|
+
- 設定値やテストの手順は写さず、所在への参照に置き換える。
|
|
73
96
|
|
|
74
97
|
## 5. 深掘り手順
|
|
75
98
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
99
|
+
内容が浅いときは、次の順で対応のない主張を探す。
|
|
100
|
+
|
|
101
|
+
1. 「再試行」「再開」の箇所ごとに、受付前・受付後・保存後で結果が変わらないかを確かめる。
|
|
102
|
+
2. 図の非同期の境界で応答を失った場合を追い、照合キーと保存記録が両側に残るかを確かめる。
|
|
103
|
+
3. 同じ ID を二つの実行へ与え、排他や重複排除が副作用を守るかを問い直す。
|
|
104
|
+
4. 設定値の参照を辿り、条件を一意に解決できなければ未決事項へ移す。
|
|
105
|
+
5. 成功条件ごとに検証・運用の担当へ渡せるかを確かめ、対応しない説明を削る。
|
|
81
106
|
|
|
82
107
|
## 6. 良い例 / 悪い例
|
|
83
108
|
|
|
84
|
-
| 観点 | 良い例
|
|
85
|
-
| ---- |
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
|
|
|
109
|
+
| 観点 | 良い例 | 悪い例 |
|
|
110
|
+
| ---- | ---------------------------------------------------------------------- | --------------------------------- |
|
|
111
|
+
| 選定 | 「応答欠落後の再送が店番の二重売上照合を増やすため、閲覧より優先する」 | 「複雑なので High」 |
|
|
112
|
+
| 失敗 | 「受付結果が不明なら同じ取引 ID と控えで照合し、未受付と確かめて再送」 | 「timeout なら retry」 |
|
|
113
|
+
| 補償 | 受付済みの売上を保持し、返品の判断を店主へ渡す | 失敗表示なら取引記録を削除する |
|
|
114
|
+
| 責任 | 「重複を検出して停止し、OPS が取引 ID で外部受付と控えを照合する」 | 「runner が担当」 |
|
|
115
|
+
| 検証 | 「応答欠落のテストで売上一件と照合待ち表示を確かめる」 | 「テストファイルがあるので pass」 |
|
|
116
|
+
| 変更 | 受付契約の変更時に、旧控えからの照合と復旧手順を確かめる | 新形式で動けば完了とする |
|
|
89
117
|
|
|
90
118
|
## 7. レビュー観点
|
|
91
119
|
|
|
92
|
-
| 観点
|
|
93
|
-
|
|
|
94
|
-
| 価値と範囲
|
|
95
|
-
|
|
|
96
|
-
| 人間の責任 | 実装主体、一次対応、技術確認、最終承認が区別されているか |
|
|
97
|
-
| 正本と証跡 | 設定・テスト・運用が一意に辿れ、未確認を確認済みと扱っていないか |
|
|
98
|
-
| 変更の波及 | フローの追加・統合・廃止で影響する索引・契約・既存記録と確認担当を辿れるか |
|
|
120
|
+
| 観点 | 確認内容 |
|
|
121
|
+
| ---------- | -------------------------------------------------- |
|
|
122
|
+
| 価値と範囲 | 守る利用者・損失と、選んだフローが対応しているか |
|
|
123
|
+
| 機械と人間 | 機械の動作、人間の一次対応、照会先が分かれているか |
|
|
99
124
|
|
|
100
125
|
## 8. 仕上げチェック
|
|
101
126
|
|
|
102
|
-
-
|
|
103
|
-
-
|
|
104
|
-
-
|
|
105
|
-
- 未決事項に担当、判断時期、解消条件、計画・管理記録への引渡し先があるか。
|
|
106
|
-
- 公開版に raw signal、実在人物の情報、秘密値が混入せず、人間が公開可否を判断できるか。
|
|
127
|
+
- 一覧の選定理由が、詳細の受入条件までたどれる。
|
|
128
|
+
- すべての成功経路に確定の記録があり、すべての失敗経路に保持状態と次の手がある。
|
|
129
|
+
- 未確認のテスト・復旧手順を、確認済みと書いていない。
|
|
@@ -11,127 +11,136 @@ specdojo:
|
|
|
11
11
|
|
|
12
12
|
System Design Cross-cutting Policy Writing Recipe
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
複数領域にまたがる失敗と回復を起点に、一般的な規約の列挙を、対象システムで判断に使える制約へ変えるための作り方を示す。
|
|
15
15
|
|
|
16
16
|
## 1. このレシピの使い方
|
|
17
17
|
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
- 値・構文・データ構造は正本へ、担当・期限・進捗は計画や登録簿へ委ねる。制約と検証結果を Rule ID で結び、判断できない境界は公開責任者へ渡す。
|
|
18
|
+
- 横断ルールは、設計索引と上位の価値から利用者・保守担当の困り事(Why)を引き継ぎ、それを防ぐ不変条件と適用境界(What)を定め、検証の入口と例外の復帰条件(How)を決める。各制約は Rule ID で検証結果と正本へたどれるようにする(Trace)。
|
|
19
|
+
- 「作成前に集める情報」をメモでそろえてから、「全体の作成手順」の順に書く。
|
|
21
20
|
|
|
22
21
|
## 2. 作成前に集める情報
|
|
23
22
|
|
|
24
|
-
|
|
|
25
|
-
| -------- |
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
| 正本 |
|
|
29
|
-
| 途中状態 | 時間切れ・応答欠落・統合失敗の時点で、外部状態・ファイル・利用枠に何が残るか
|
|
30
|
-
| 観測 |
|
|
31
|
-
|
|
|
32
|
-
| 不足 | 未定義の上限・優先順・通知先は何か。いつまでに誰が決めるか |
|
|
23
|
+
| 項目 | 集める情報 | 取り出し元 |
|
|
24
|
+
| -------- | ---------------------------------------------------------------------------- | -------------------------------- |
|
|
25
|
+
| 困り事 | 誰が何を引き継げず、どの失敗で費用・作業負荷が増えるか | 上位の価値・課題、障害の記録 |
|
|
26
|
+
| 実行経路 | CLI、API、ジョブ、生成、外部プロセス、保存先のどこが共通制約を持つか | システム設計索引 |
|
|
27
|
+
| 正本 | 値と構造を決める設定・schema・リファレンス、実在する検証コマンドと対象ケース | 実装担当への確認、リポジトリ |
|
|
28
|
+
| 途中状態 | 時間切れ・応答欠落・統合失敗の時点で、外部状態・ファイル・利用枠に何が残るか | 実装担当への確認、失敗注入の結果 |
|
|
29
|
+
| 観測 | 誰がどの証跡から対象の実行を特定し、停止と回復を判断するか | 運用担当への確認、ログの実例 |
|
|
30
|
+
| 不足 | 正本に値がない上限・優先順・通知先 | 確認の過程のメモ |
|
|
33
31
|
|
|
34
32
|
## 3. 全体の作成手順
|
|
35
33
|
|
|
36
|
-
1.
|
|
37
|
-
2.
|
|
38
|
-
3.
|
|
39
|
-
4.
|
|
40
|
-
5.
|
|
41
|
-
6.
|
|
34
|
+
1. 概要を最初に書き、対象の実行経路と対象外を決める。境界が決まらないと、ルールの抜けを判定できない。
|
|
35
|
+
2. 代表的な途中失敗を 1 つずつ追い、各ルール詳細を書く。一覧から書くと、実装の説明を規則に見せかけやすい。
|
|
36
|
+
3. 詳細がそろってから、同じ失敗を防ぐ制約をまとめてルール一覧を作る。
|
|
37
|
+
4. 承認済みの逸脱だけを例外に分け、未承認の不適合と混ぜない。
|
|
38
|
+
5. 一つの規則変更から実装・schema・生成物・回帰対象をたどり、関連導線を書く。
|
|
39
|
+
6. 最後に、確認できない値や判断待ちを未決事項に分け、どの Rule の受入を止めるかを書く。
|
|
42
40
|
|
|
43
41
|
## 4. 各章の書き方
|
|
44
42
|
|
|
45
43
|
### 4.1. 概要
|
|
46
44
|
|
|
47
|
-
|
|
48
|
-
- HTTP API がないときの CLI エラー、DB がないときのファイル保存など、技術が非該当でも代わりの責務は残っていないか。代替も不要なら構成から説明できるか。
|
|
49
|
-
- 誰が実装と運用を確認し、誰が公開の説明責任を持つか。
|
|
45
|
+
問い:
|
|
50
46
|
|
|
51
|
-
|
|
47
|
+
- 共通規則がないと、誰が同じ調査や回復を繰り返すか。
|
|
48
|
+
- 安全な保存と速度などが競合したとき、何を先に守るか。
|
|
49
|
+
|
|
50
|
+
コツ:
|
|
51
|
+
|
|
52
|
+
- HTTP API や DB がなくても、CLI のエラーやファイル保存の途中状態で同じ責務が残る。技術の不在を対象外の理由にしない。
|
|
53
|
+
- 上位の価値や背景を写したくなったら、上位成果物への参照に置き換える。
|
|
52
54
|
|
|
53
55
|
### 4.2. ルール一覧
|
|
54
56
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
-
|
|
57
|
+
問い:
|
|
58
|
+
|
|
59
|
+
- 先に設定や契約を決めなければ確認できない規則はどれか。
|
|
60
|
+
- 要約と必須度を組み合わせて読んでも、意図が逆にならないか。
|
|
58
61
|
|
|
59
|
-
|
|
62
|
+
コツ:
|
|
63
|
+
|
|
64
|
+
- 構成上の実行経路を横に並べ、どの経路にも効く規則がない領域を探す。
|
|
65
|
+
- 規則を書いたことと実装済みの証拠を分けて聞く。照合していなければ未照合と書く。
|
|
60
66
|
|
|
61
67
|
### 4.3. 各ルール詳細
|
|
62
68
|
|
|
63
|
-
|
|
64
|
-
- どの正本のキーと単位を使い、何を入力し、どの観測なら合格か。検証コマンドはその repository で実行でき、対象ケースへ到達するか。
|
|
65
|
-
- 条件を判定できない場合、どの受入を保留し、誰へ照合を依頼するか。
|
|
69
|
+
問い:
|
|
66
70
|
|
|
67
|
-
|
|
71
|
+
- 同じ入力と前提なら、次の動作と合否は一つに決まるか。
|
|
72
|
+
- 検証コマンドはそのリポジトリで実行でき、対象ケースへ到達するか。
|
|
68
73
|
|
|
69
|
-
|
|
70
|
-
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
71
|
-
| エラー | 入力不正、実行失敗、利用制限、競合、保護違反を何から識別するか。利用者は保持記録から訂正・回復・人間判断のどれを選べるか |
|
|
72
|
-
| 冪等 | 同じ論理処理と別 attempt をどう識別するか。応答欠落時に外部受付・保存・統合のどこを照合し、二重処理を見分けるか |
|
|
73
|
-
| 再試行 | 冪等性の前提、signal の分類、criticality を使う場合の区分はどこで確認するか。初回を含むかという回数の数え方、attempt・backoff 上限、fallback の候補条件、上限到達時の処置を一意に選べるか |
|
|
74
|
-
| 時間制御 | 経路別の設定キー・単位は何か。上限直前・到達時にどの子プロセスを終了し、部分出力・保存状態をどう確認して再開を判断するか |
|
|
75
|
-
| ログ・追跡 | 診断と監査で何を追うか。親子実行と attempt を結び、秘密を除去した後も失敗を特定できるか。保持・閲覧・検知・通知・一次対応の正本と担当へ進めるか |
|
|
76
|
-
| 設定 | 項目ごとにどの上書き階層が存在し、競合時の優先順・反映時点を何で確かめるか。不正値と指定なしで結果はどう変わるか |
|
|
77
|
-
| 境界・権限 | 各モジュールが変更できる状態と呼出し先は何か。権限を越える経路や、生成物から正本へ状態変更が逆流する経路をどう検出するか |
|
|
74
|
+
コツ:
|
|
78
75
|
|
|
79
|
-
|
|
76
|
+
- 一つの途中失敗を、再試行・時間切れ・設定の競合・ログの欠落の順に追い、答えを適用境界と検証の説明に入れる。
|
|
77
|
+
- 上限値・設定キー・構文は写さず、正本への参照に置き換える。分からない値は推測で埋めず、実装担当に聞く。
|
|
80
78
|
|
|
81
79
|
### 4.4. 例外
|
|
82
80
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
-
|
|
81
|
+
問い:
|
|
82
|
+
|
|
83
|
+
- 一時的に許した逸脱か、既に起きた問題か、将来の懸念か。
|
|
84
|
+
- 期限が来たとき、どの検証で通常規則へ戻ったと判断するか。
|
|
86
85
|
|
|
87
|
-
|
|
86
|
+
コツ:
|
|
87
|
+
|
|
88
|
+
- 「緊急なら」など条件の広い許可を求められたら、対象の Rule と期限を具体的に聞き直す。
|
|
88
89
|
|
|
89
90
|
### 4.5. 関連導線
|
|
90
91
|
|
|
92
|
+
問い:
|
|
93
|
+
|
|
91
94
|
- 読む人はその参照で何を判断するか。
|
|
92
|
-
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
+
- schema を変えたとき、古い記録・生成物・CLI の利用者に何が起きるか。
|
|
96
|
+
|
|
97
|
+
コツ:
|
|
95
98
|
|
|
96
|
-
|
|
99
|
+
- 見出し・表・本文で同じ文書を同じ名称で呼ぶ。略号だけでは参照先を特定できない。
|
|
100
|
+
- 参照先が未作成なら未作成と書き、作成済みのように扱わない。
|
|
97
101
|
|
|
98
102
|
### 4.6. 未決事項と公開条件
|
|
99
103
|
|
|
100
|
-
|
|
101
|
-
- 誰がいつ判断し、解消しない間の受入・公開に何が制限されるか。
|
|
102
|
-
- 計画・登録簿の実 ID がない場合、誰が次の計画更新で接続するか。
|
|
104
|
+
問い:
|
|
103
105
|
|
|
104
|
-
|
|
106
|
+
- 不明な事実か、意思決定待ちか、仮定か。
|
|
107
|
+
- 解消しない間、どの Rule の受入を止めるか。
|
|
105
108
|
|
|
106
|
-
|
|
109
|
+
コツ:
|
|
110
|
+
|
|
111
|
+
- 不明は _TODO_、判断待ちは _UNDECIDED_、仮定は _ASSUMPTION_ で書き分ける。
|
|
112
|
+
- 未発行の作業 ID を、発行済みの証拠として数えない。
|
|
107
113
|
|
|
108
114
|
## 5. 深掘り手順
|
|
109
115
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
116
|
+
内容が浅いときは、次の順で対応のない主張を探す。
|
|
117
|
+
|
|
118
|
+
1. 各 Rule が、概要のどの困り事を防ぐかを確かめ、対応のない実装解説を外す。
|
|
119
|
+
2. 同じ失敗の再実行と並列の別実行を追い、識別・重複防止・時間上限・停止・観測が途切れる箇所を探す。
|
|
120
|
+
3. 手段だけがあり、支える制約や防ぐ失敗を説明できない Enforcement を探す。
|
|
121
|
+
4. 途切れた箇所の正本を確かめ、根拠がなければ固定値で穴を隠さず未決事項へ移す。
|
|
113
122
|
|
|
114
123
|
## 6. 良い例 / 悪い例
|
|
115
124
|
|
|
116
|
-
| 観点
|
|
117
|
-
|
|
|
118
|
-
|
|
|
119
|
-
|
|
|
120
|
-
|
|
|
121
|
-
|
|
|
122
|
-
|
|
|
125
|
+
| 観点 | 良い例 | 悪い例 |
|
|
126
|
+
| -------- | ------------------------------------------------------------- | -------------------------------------- |
|
|
127
|
+
| 対象範囲 | 「API はないが CLI の失敗記録を共通化し、再開対象を選べる」 | 「API がないのでエラー・監視は対象外」 |
|
|
128
|
+
| 冪等 | 同じ論理処理と attempt を区別し、保存・受付を照合して再開する | 同じファイル名へ書くので安全とする |
|
|
129
|
+
| 時間制御 | 上限到達では部分出力を保持して停止し、受付結果を照合して再開 | 「タイムアウトしたら再実行する」 |
|
|
130
|
+
| 設定 | 同じ項目の競合指定を与え、正本の優先順と反映時点を確かめる | 全項目で CLI が優先すると推測する |
|
|
131
|
+
| 実装状況 | 「未照合、設定確定後に失敗注入で確かめる」 | 規則を書いたので実装済みとする |
|
|
123
132
|
|
|
124
133
|
## 7. レビュー観点
|
|
125
134
|
|
|
126
|
-
| 観点
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
|
|
|
135
|
+
| 観点 | 確認内容 |
|
|
136
|
+
| ------------ | ---------------------------------------------------------------- |
|
|
137
|
+
| 目的との対応 | 各 Rule が概要の困り事につながり、個別機能の手順を抱えていないか |
|
|
138
|
+
| 合否の再現 | 正本・入力・期待結果がつながり、第三者が同じ判定を出せるか |
|
|
139
|
+
| 回復 | 途中状態から安全に再開でき、判断できなければ人へ情報を渡せるか |
|
|
140
|
+
| 変更の追従 | Rule の変更から、実装・schema・生成物・回帰対象をたどれるか |
|
|
132
141
|
|
|
133
142
|
## 8. 仕上げチェック
|
|
134
143
|
|
|
135
|
-
-
|
|
136
|
-
-
|
|
137
|
-
-
|
|
144
|
+
- 各 Rule が概要の困り事に対応し、検証の入口と正本までたどれる。
|
|
145
|
+
- 同じ状態に異なる動作を求める Rule がない。
|
|
146
|
+
- 確認していない値や実装状況を、確認済みのように書いていない。
|
|
@@ -11,112 +11,131 @@ specdojo:
|
|
|
11
11
|
|
|
12
12
|
System Design Index Writing Recipe
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
変更する人が最初に直す正本と確かめ方を選べる索引の作り方を示す。
|
|
15
15
|
|
|
16
16
|
## 1. このレシピの使い方
|
|
17
17
|
|
|
18
|
-
-
|
|
19
|
-
- 得たい成果は「設計領域から正本へ、変更目的から検証へたどれる状態」とする。所在、責任、追従先を同じ行で結び付ける。
|
|
20
|
-
- ファイルやコマンドの存在確認と、構成・公開の承認を分ける。値・構文・構造の詳細を作り込まず、未決事項を判断者へ渡す。
|
|
18
|
+
- 索引は、正本探しと二重更新(Why)に応え、設計領域ごとの正本・派生物・非該当・未確認(What)を定め、変更目的から更新先と検証へたどる経路(How)を示す。所在・更新責任・追従先は同じ行で結び付ける(Trace)。
|
|
21
19
|
|
|
22
20
|
## 2. 作成前に集める情報
|
|
23
21
|
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
| 利用目的
|
|
27
|
-
| 対象境界
|
|
28
|
-
| 正本候補
|
|
29
|
-
| 生成経路
|
|
30
|
-
| 確認経路
|
|
31
|
-
| 関連仕様
|
|
32
|
-
| 責任と留保 | 更新者、確認者、承認者、根拠不足の領域と判断時機は何か |
|
|
22
|
+
| 項目 | 集める情報 | 取り出し元 |
|
|
23
|
+
| -------- | ------------------------------------------------------ | --------------------------------- |
|
|
24
|
+
| 利用目的 | 誰がどの設計情報を探し、どの領域に困っているか | 開発担当・引継ぎを受けた担当 |
|
|
25
|
+
| 対象境界 | 対象システム、外部へ任せる部分、任意で使う構成 | システム概要・構成図 |
|
|
26
|
+
| 正本候補 | 値を変えるとき最初に編集するファイルと基準ディレクトリ | 各リポジトリの配置、開発担当 |
|
|
27
|
+
| 生成経路 | 生成の入力、script・サブコマンド、出力先 | `package.json` などの script 定義 |
|
|
28
|
+
| 確認経路 | 変更後に流す検査と対象ケース、観測できる結果 | テスト・CI の定義、品質担当 |
|
|
29
|
+
| 関連仕様 | 判断の根拠を持つ文書と、その現行・廃止状態 | 文書体系の一覧 |
|
|
33
30
|
|
|
34
31
|
## 3. 全体の作成手順
|
|
35
32
|
|
|
36
|
-
1.
|
|
37
|
-
2.
|
|
38
|
-
3.
|
|
39
|
-
4.
|
|
40
|
-
5.
|
|
41
|
-
6.
|
|
33
|
+
1. 概要に対象と対象外を書く。範囲が決まらないと、SSOT 一覧に載せる領域が決まらない。
|
|
34
|
+
2. SSOT 一覧で、候補を正本・派生物・業務記録・未確認に仕分ける。
|
|
35
|
+
3. 自動生成物で、正本から再生成できる入力と出力を一対にする。正本の後に書くと、生成物を正本に載せずに済む。
|
|
36
|
+
4. 変更の入口で、代表的な変更を更新先から検証まで一度たどり、たどれない箇所は前の章で直す。
|
|
37
|
+
5. 関連ドキュメント導線で、読み手が判断に使う文書だけを並べる。
|
|
38
|
+
6. 途中でメモした未確認・未決を留保事項にまとめる。
|
|
42
39
|
|
|
43
40
|
## 4. 各章の書き方
|
|
44
41
|
|
|
45
42
|
### 4.1. 概要
|
|
46
43
|
|
|
47
|
-
|
|
48
|
-
- 対象外と外部依存を混同していないか。
|
|
49
|
-
- 誰が更新し、QE は何を確認し、人間は何を承認するか。
|
|
44
|
+
問い:
|
|
50
45
|
|
|
51
|
-
|
|
46
|
+
- どの利用者の、どの調査・引継ぎを助けるか。
|
|
47
|
+
- 対象外と、外部に任せる部分はどこか。
|
|
48
|
+
|
|
49
|
+
コツ:
|
|
50
|
+
|
|
51
|
+
- 範囲は機能や実行単位(CLI、日次処理など)で区切ると対象外が見える。外部に任せる部分は、連携の正本として残る。
|
|
52
|
+
- プロジェクトの背景は写さず、上位の文書への参照に置き換える。
|
|
52
53
|
|
|
53
54
|
### 4.2. SSOT 一覧
|
|
54
55
|
|
|
56
|
+
問い:
|
|
57
|
+
|
|
55
58
|
- 値を変えるとき、最初に編集するのはどのファイルか。
|
|
56
|
-
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
+
- 「なし」と書く領域は、構成上ないのか、まだ調べていないのか。
|
|
60
|
+
|
|
61
|
+
コツ:
|
|
59
62
|
|
|
60
|
-
|
|
63
|
+
- 開発担当に「この値を変えるとき最初にどこを開くか」と聞くと、派生物ではなく正本が出てくる。
|
|
64
|
+
- DB がない構成では保存形式と移行の契約が、監視では形式・通知を決める設定が抜けやすい。
|
|
61
65
|
|
|
62
66
|
### 4.3. 自動生成物
|
|
63
67
|
|
|
68
|
+
問い:
|
|
69
|
+
|
|
64
70
|
- 入力、コマンド、出力が実際につながっているか。
|
|
65
|
-
-
|
|
66
|
-
|
|
67
|
-
|
|
71
|
+
- 生成後にどこを見れば更新を確かめられるか。
|
|
72
|
+
|
|
73
|
+
コツ:
|
|
68
74
|
|
|
69
|
-
|
|
75
|
+
- 出力名からコマンドを推測しやすい。script 定義を開いて照合する。
|
|
76
|
+
- 実行結果を保持するファイルは、生成物に見えても業務記録として分ける。
|
|
70
77
|
|
|
71
78
|
### 4.4. 変更の入口
|
|
72
79
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
-
|
|
76
|
-
-
|
|
80
|
+
問い:
|
|
81
|
+
|
|
82
|
+
- この変更が起きたら、最初に何を変え、何が追従するか。
|
|
83
|
+
- どのケースを見れば、今回の変更を判定できるか。
|
|
77
84
|
|
|
78
|
-
|
|
85
|
+
コツ:
|
|
86
|
+
|
|
87
|
+
- 品質担当に「この変更で壊れやすいのはどこか」と聞くと、正常系以外のケースを選べる。
|
|
88
|
+
- これから行う確認と実行済みの証跡を混ぜやすい。
|
|
79
89
|
|
|
80
90
|
### 4.5. 関連ドキュメント導線
|
|
81
91
|
|
|
92
|
+
問い:
|
|
93
|
+
|
|
82
94
|
- 読み手はこの参照で何を判断するか。
|
|
83
|
-
-
|
|
84
|
-
|
|
95
|
+
- 未作成の文書は、当面どこを参照するか。
|
|
96
|
+
|
|
97
|
+
コツ:
|
|
85
98
|
|
|
86
|
-
|
|
99
|
+
- 略号だけで分類すると、同じ文書を別名で呼び分けやすい。参照目的で分ける。
|
|
100
|
+
- 同名・後継・廃止の文書を取り違えやすい。
|
|
87
101
|
|
|
88
|
-
### 4.6.
|
|
102
|
+
### 4.6. 留保事項
|
|
103
|
+
|
|
104
|
+
問い:
|
|
89
105
|
|
|
90
106
|
- 不明な事実、意思決定待ち、仮定のどれか。
|
|
91
|
-
-
|
|
92
|
-
|
|
107
|
+
- 解消したら、どの行・設定・手順へ反映するか。
|
|
108
|
+
|
|
109
|
+
コツ:
|
|
93
110
|
|
|
94
|
-
|
|
111
|
+
- 実装が動いたことと、未整備の監視を残したまま使えるかは別の論点として分ける。
|
|
95
112
|
|
|
96
113
|
## 5. 深掘り手順
|
|
97
114
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
115
|
+
内容が浅いときは、次の順で対応のない主張を探す。
|
|
116
|
+
|
|
117
|
+
1. 変更の入口の各行が、どの正本から始まり、どの検証で終わるかを確かめる。欠ける行は留保事項へ移す。
|
|
118
|
+
2. 非該当の行ごとに、代わりの保存・連携・観測の手段が残っているかを確かめる。
|
|
119
|
+
3. 自動生成物の各行の入力が、SSOT 一覧の正本にあるかを確かめる。ない行は正本か業務記録かを見直す。
|
|
101
120
|
|
|
102
121
|
## 6. 良い例 / 悪い例
|
|
103
122
|
|
|
104
|
-
| 観点 | 良い例
|
|
105
|
-
| ---------- |
|
|
106
|
-
| パスの解釈 |
|
|
107
|
-
| 検証の範囲 |
|
|
108
|
-
|
|
|
123
|
+
| 観点 | 良い例 | 悪い例 |
|
|
124
|
+
| ---------- | ---------------------------------------------------------------- | ------------------------------------- |
|
|
125
|
+
| パスの解釈 | 複数リポジトリの入力・出力に、それぞれの基準ディレクトリを添える | 同名の `src/` を基準なしで並べる |
|
|
126
|
+
| 検証の範囲 | 「二つの実行が別の保存先を使うことを、分離テストで確かめる」 | 「代表実行が成功したので分離も確認」 |
|
|
127
|
+
| 検証の段階 | CI の検査成功と、実機での確認が未実施であることを分けて書く | CI が成功したので運用も確認済みとする |
|
|
109
128
|
|
|
110
129
|
## 7. レビュー観点
|
|
111
130
|
|
|
112
|
-
| 観点
|
|
113
|
-
|
|
|
114
|
-
| 所在
|
|
115
|
-
|
|
|
116
|
-
|
|
|
131
|
+
| 観点 | 確認内容 |
|
|
132
|
+
| -------- | ---------------------------------------------------------- |
|
|
133
|
+
| 所在 | 初めて読む開発担当が、派生物ではなく正本を選べるか |
|
|
134
|
+
| 検証経路 | 品質担当が、コマンド・対象ケース・期待結果を一組で選べるか |
|
|
135
|
+
| 委譲 | 値・電文・設定の中身を写さず、正本への導線だけを置いたか |
|
|
117
136
|
|
|
118
137
|
## 8. 仕上げチェック
|
|
119
138
|
|
|
120
|
-
-
|
|
121
|
-
-
|
|
122
|
-
-
|
|
139
|
+
- 非該当の行に、代わりの手段か、代わりが要らない理由がある。
|
|
140
|
+
- 未確認の領域を確定情報にしていない。
|
|
141
|
+
- 実在しない文書やコマンドを現行の導線にしていない。
|