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.
Files changed (284) hide show
  1. package/.github/agents/specdojo-orchestrator.md +4 -1
  2. package/CHANGELOG.md +64 -0
  3. package/dist/catalog/catalog.js +16 -14
  4. package/dist/commands/agent.js +5 -3
  5. package/dist/commands/build.js +69 -10
  6. package/dist/commands/git.js +206 -0
  7. package/dist/commands/init.js +4 -2
  8. package/dist/commands/where.js +25 -0
  9. package/dist/dashboard/dashboard.js +5 -3
  10. package/dist/dashboard/routines.js +4 -7
  11. package/dist/dashboard/timeline.js +14 -14
  12. package/dist/docs/index-command.js +2 -2
  13. package/dist/docs/yaml-business-tables.js +243 -0
  14. package/dist/docs/yaml-interface-tables.js +106 -0
  15. package/dist/docs/yaml-pages-command.js +5 -3
  16. package/dist/docs/yaml-pages.js +146 -3
  17. package/dist/docs/yaml-table-shared.js +70 -0
  18. package/dist/docs/yaml-tables.js +39 -0
  19. package/dist/exec/agent-config.js +9 -0
  20. package/dist/exec/agent-protected-config.js +2 -0
  21. package/dist/exec/commands.js +31 -18
  22. package/dist/exec/events.js +34 -14
  23. package/dist/exec/evidence.js +13 -3
  24. package/dist/exec/parent-validation.js +56 -3
  25. package/dist/exec/plans-core.js +21 -2
  26. package/dist/exec/plans-generation.js +6 -7
  27. package/dist/exec/post-integration.js +162 -0
  28. package/dist/exec/queue-command.js +166 -0
  29. package/dist/exec/queue.js +285 -0
  30. package/dist/exec/register-foreign-wait.js +84 -0
  31. package/dist/exec/repo-integration-sync.js +17 -5
  32. package/dist/exec/reporter.js +2 -2
  33. package/dist/exec/results.js +24 -4
  34. package/dist/exec/review-kata.js +4 -1
  35. package/dist/exec/run/agent-pipeline.js +3 -2
  36. package/dist/exec/run/agent.js +12 -6
  37. package/dist/exec/run/change-scope.js +365 -0
  38. package/dist/exec/run/deferred-cleanup.js +31 -0
  39. package/dist/exec/run/in-place.js +4 -1
  40. package/dist/exec/run/job-lock.js +66 -0
  41. package/dist/exec/run/job-sequence.js +137 -0
  42. package/dist/exec/run/job.js +56 -19
  43. package/dist/exec/run/lifecycle-commands.js +1 -1
  44. package/dist/exec/run/lock.js +22 -1
  45. package/dist/exec/run/register-command.js +8 -5
  46. package/dist/exec/run/register-mode.js +68 -8
  47. package/dist/exec/run/register-resume.js +68 -14
  48. package/dist/exec/run/register-state.js +13 -8
  49. package/dist/exec/run/register-worktree.js +140 -125
  50. package/dist/exec/run/schedule-mode.js +75 -14
  51. package/dist/exec/run/schedule-prepare.js +3 -0
  52. package/dist/exec/run/schedule-task.js +88 -38
  53. package/dist/exec/run/shared.js +5 -0
  54. package/dist/exec/schedule/schedule.js +116 -4
  55. package/dist/exec/shared.js +1 -1
  56. package/dist/exec/smoke.js +190 -0
  57. package/dist/exec/strategy.js +13 -3
  58. package/dist/exec/task-view.js +6 -4
  59. package/dist/exec/trial-commands.js +5 -2
  60. package/dist/exec/trial-core.js +6 -1
  61. package/dist/exec/validation-metrics.js +181 -0
  62. package/dist/exec/worktree-cleanup-lock.js +26 -0
  63. package/dist/exec/worktree-command.js +9 -1
  64. package/dist/exec/worktree-ops-commit.js +2 -2
  65. package/dist/exec/worktree.js +13 -2
  66. package/dist/grade/command-apply.js +3 -3
  67. package/dist/grade/command-inspect.js +5 -3
  68. package/dist/grade/command-plan.js +1 -1
  69. package/dist/grade/command-run.js +5 -1
  70. package/dist/grade/run.js +64 -8
  71. package/dist/job/definition.js +84 -8
  72. package/dist/job/job.js +79 -23
  73. package/dist/register/authoring-sources.js +22 -16
  74. package/dist/register/maintenance-commands.js +2 -2
  75. package/dist/register/register.js +31 -7
  76. package/dist/routine/definition.js +9 -0
  77. package/dist/routine/routine.js +137 -43
  78. package/dist/routine/status.js +62 -0
  79. package/dist/schedule/schedule.js +38 -39
  80. package/dist/shared/agent-types.js +5 -0
  81. package/dist/shared/cross-process-lock.js +9 -1
  82. package/dist/shared/dist-freshness.js +8 -2
  83. package/dist/shared/git-environment.js +2 -1
  84. package/dist/shared/git.js +44 -1
  85. package/dist/shared/lefthook-scaffold.js +3 -0
  86. package/dist/shared/local-config.js +244 -0
  87. package/dist/shared/specdojo-config.js +34 -20
  88. package/dist/shared/specdojo-gitignore.js +1 -0
  89. package/dist/shared/text.js +9 -1
  90. package/dist/shared/where-alias.js +13 -0
  91. package/dist/specdojo.js +4 -0
  92. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +2 -0
  93. package/docs/ja/specdojo/guides/exec-config-guide.md +23 -4
  94. package/docs/ja/specdojo/guides/exec-operation-guide.md +44 -1
  95. package/docs/ja/specdojo/guides/job-sequence-guide.md +77 -0
  96. package/docs/ja/specdojo/guides/quick-start-guide.md +3 -3
  97. package/docs/ja/specdojo/guides/register-operation-guide.md +1 -1
  98. package/docs/ja/specdojo/guides/routine-operation-guide.md +11 -6
  99. package/docs/ja/specdojo/guides/schedule-design-guide.md +20 -17
  100. package/docs/ja/specdojo/guides/waza-guide.md +12 -8
  101. package/docs/ja/specdojo/recipes/bac-recipe.md +66 -49
  102. package/docs/ja/specdojo/recipes/bes-recipe.md +90 -54
  103. package/docs/ja/specdojo/recipes/bps-recipe.md +88 -139
  104. package/docs/ja/specdojo/recipes/br-recipe.md +40 -47
  105. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +97 -109
  106. package/docs/ja/specdojo/recipes/cdfd-recipe.md +85 -146
  107. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +91 -110
  108. package/docs/ja/specdojo/recipes/cnd-recipe.md +79 -69
  109. package/docs/ja/specdojo/recipes/cpd-recipe.md +78 -64
  110. package/docs/ja/specdojo/recipes/cxd-recipe.md +92 -75
  111. package/docs/ja/specdojo/recipes/ifd-recipe.md +79 -68
  112. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +78 -105
  113. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +105 -71
  114. package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +60 -49
  115. package/docs/ja/specdojo/recipes/pm-members-recipe.md +50 -51
  116. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +59 -51
  117. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +69 -56
  118. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +37 -56
  119. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -53
  120. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +52 -79
  121. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +64 -93
  122. package/docs/ja/specdojo/recipes/prj-charter-recipe.md +71 -106
  123. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +78 -157
  124. package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +62 -111
  125. package/docs/ja/specdojo/recipes/prj-scope-recipe.md +67 -123
  126. package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +60 -96
  127. package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +61 -105
  128. package/docs/ja/specdojo/recipes/stsd-recipe.md +79 -109
  129. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +78 -55
  130. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +82 -73
  131. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +78 -59
  132. package/docs/ja/specdojo/recipes/tsd-recipe.md +149 -129
  133. package/docs/ja/specdojo/references/command-reference.md +257 -117
  134. package/docs/ja/specdojo/references/deliverables-reference.md +21 -12
  135. package/docs/ja/specdojo/references/specdojo-config-reference.md +37 -2
  136. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +101 -257
  137. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +102 -228
  138. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +19 -28
  139. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +16 -67
  140. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +30 -51
  141. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +41 -61
  142. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +22 -50
  143. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +24 -56
  144. package/docs/ja/specdojo/rulebooks/br-rulebook.md +13 -38
  145. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +41 -76
  146. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +18 -93
  147. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +18 -52
  148. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +109 -147
  149. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +80 -108
  150. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +21 -46
  151. package/docs/ja/specdojo/rulebooks/cdr-rulebook.md +144 -0
  152. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +27 -48
  153. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +37 -50
  154. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +52 -69
  155. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +33 -86
  156. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +16 -32
  157. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +45 -131
  158. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +69 -275
  159. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +20 -112
  160. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +23 -56
  161. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +12 -145
  162. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +39 -47
  163. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +37 -56
  164. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +118 -175
  165. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +5 -14
  166. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +22 -66
  167. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +36 -94
  168. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +59 -81
  169. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +31 -131
  170. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +50 -104
  171. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +51 -61
  172. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +38 -45
  173. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +14 -20
  174. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +26 -38
  175. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +26 -107
  176. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +42 -49
  177. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +14 -22
  178. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +21 -44
  179. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +41 -64
  180. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +14 -38
  181. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +34 -61
  182. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +27 -50
  183. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +70 -199
  184. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +65 -153
  185. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +74 -150
  186. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +11 -23
  187. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +99 -176
  188. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +35 -61
  189. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +75 -117
  190. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +31 -60
  191. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +26 -81
  192. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +32 -70
  193. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +45 -87
  194. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +48 -101
  195. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +44 -80
  196. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +59 -127
  197. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +31 -50
  198. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +42 -109
  199. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +29 -42
  200. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +29 -87
  201. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +62 -84
  202. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +11 -61
  203. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +91 -106
  204. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +25 -34
  205. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +30 -53
  206. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +23 -35
  207. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +27 -45
  208. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +37 -45
  209. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +45 -46
  210. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +37 -48
  211. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +25 -29
  212. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +28 -35
  213. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +36 -41
  214. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +5 -18
  215. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +16 -37
  216. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +23 -97
  217. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +39 -57
  218. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +43 -116
  219. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +16 -51
  220. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +47 -92
  221. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +25 -84
  222. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +44 -107
  223. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +39 -49
  224. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +42 -49
  225. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +64 -89
  226. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +90 -189
  227. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +45 -105
  228. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +6 -12
  229. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +49 -68
  230. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +51 -60
  231. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +46 -50
  232. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +39 -64
  233. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +47 -60
  234. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +69 -70
  235. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +65 -72
  236. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +35 -46
  237. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +49 -66
  238. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +64 -139
  239. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +41 -108
  240. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +49 -144
  241. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +67 -155
  242. package/docs/ja/specdojo/samples/bds-sample.md +58 -71
  243. package/docs/ja/specdojo/samples/bes-index-sample.md +20 -37
  244. package/docs/ja/specdojo/samples/bes-sample.md +43 -53
  245. package/docs/ja/specdojo/samples/bps-sample.md +42 -54
  246. package/docs/ja/specdojo/samples/br-sample.md +40 -52
  247. package/docs/ja/specdojo/samples/ccd-sample.md +0 -1
  248. package/docs/ja/specdojo/samples/cdr-sample.md +78 -0
  249. package/docs/ja/specdojo/samples/cdsd-sample.md +47 -63
  250. package/docs/ja/specdojo/samples/clis-sample.md +70 -77
  251. package/docs/ja/specdojo/samples/dec-sample.md +2 -3
  252. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +0 -2
  253. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +0 -2
  254. package/docs/ja/specdojo/samples/job-sequence.yaml +67 -0
  255. package/docs/ja/specdojo/samples/mip-index-sample.md +98 -20
  256. package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +26 -19
  257. package/docs/ja/specdojo/samples/pm-organization-sample.md +39 -50
  258. package/docs/ja/specdojo/samples/pm-plan-sample.md +61 -67
  259. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +31 -45
  260. package/docs/ja/specdojo/samples/pm-raci-sample.md +31 -37
  261. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +32 -48
  262. package/docs/ja/specdojo/samples/prj-charter-sample.md +42 -59
  263. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +55 -61
  264. package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +30 -33
  265. package/docs/ja/specdojo/samples/sf-index-sample.md +13 -55
  266. package/docs/ja/specdojo/samples/sf-sample.md +73 -85
  267. package/docs/ja/specdojo/samples/sld-sample.md +60 -79
  268. package/docs/ja/specdojo/samples/uis-sample.md +98 -121
  269. package/docs/ja/specdojo/standards/job-definition-standard.md +24 -9
  270. package/docs/ja/specdojo/templates/cdr-template.md +58 -0
  271. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +2 -1
  272. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +42 -5
  273. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +35 -0
  274. package/docs/specdojo/schemas/v1/job-run.schema.yaml +23 -0
  275. package/docs/specdojo/schemas/v1/job.schema.yaml +63 -2
  276. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +2 -2
  277. package/package.json +9 -6
  278. package/templates/antigravity/orchestrator.md +4 -1
  279. package/templates/claude/agents/specdojo-orchestrator.md +4 -1
  280. package/templates/codex/agents/specdojo-orchestrator.toml +4 -1
  281. package/templates/codex/orchestrator.md +4 -1
  282. package/templates/init-exec-defaults.yaml +13 -0
  283. package/templates/lefthook/tools/specdojo-pre-commit.mjs +8 -0
  284. 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. 一覧で事故候補を比較する。通常処理より優先する理由を利用者の損失から説明する。候補が5件を超えたら、同じ事故を防ぐ候補の統合、既存との置換、対象外への整理を行い、整理後の件数と選定理由を確認してから詳細へ進む。
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
- - 具体化: 設計索引と状態用語の定義先を確かめ、公開対象と除外する情報、最終判断を担う人間の Role code を短く書く。廃止済みの根拠しかなければ、現行仕様との照合を後続作業へ渡す。
48
- - 対比: 「販売要求から受付照合まで。購入履歴は除外し、PO が公開を判断する」なら範囲を確認できる。「全体を安全にする」では入口・出口・判断者を決められない。
43
+ 問い:
44
+
45
+ - どの操作からどの業務結果までを扱い、通常処理を外した理由は何か。
46
+ - 公開版に、実行記録や個人を識別できる情報が紛れていないか。
47
+
48
+ コツ:
49
+
50
+ - 状態用語や対象者の説明を写したくなったら、業務フロー・状態遷移仕様への参照に置き換える。
51
+ - 根拠が廃止済みの文書だけなら、現行仕様との照合を未決事項にする。
49
52
 
50
53
  ### 4.2. 重要フロー一覧
51
54
 
52
- - 問い: 誰の損失を防ぐか。放置すると何が壊れるか。成功すればどの負荷が減るか。
53
- - 具体化: 対象者・事故論点・業務影響・期待効果を一行で結び、候補間で影響を比較する。単純な処理でも重複・誤承認の影響を見落とさない。
54
- - 対比: 「応答欠落後の再送が店番の二重売上照合を増やすため、閲覧より優先する」なら選定を説明できる。「複雑なので High」では他候補と比較できない。
55
+ 問い:
56
+
57
+ - 放置すると誰の何が壊れ、成功すればどの負荷が減るか。
58
+ - その損失は、ほかの候補より重いか。
59
+
60
+ コツ:
61
+
62
+ - 対象者・事故・影響・効果を 1 行で言えない候補は、まだ詳細へ進めない。
55
63
 
56
64
  ### 4.3. フロー詳細
57
65
 
58
- - 問い: 誰の何の要求で始まり、何を受け取り何を返すか。どの記録があれば成功と言えるか。再送で二度目の副作用が起きないか。取消不能なら何を保持して誰が照合するか。
59
- - 具体化: 処理主体と保存先を分け、境界を越える要求・応答を同じ識別子で追う。矢印の凡例で同期・非同期を、保存記録で要求受付・業務完了を読み分けられるか試す。保存前後の中断から保持・補償・再開条件を決め、利用者が確認できる受入結果へ結ぶ。
60
- - 対比: 「受付結果不明なら同じ取引 ID と控えを保持して照合し、未受付と確認して再送する」なら次の手が決まる。「timeout なら retry」では受付済みの副作用を判断できない。
66
+ 問い:
67
+
68
+ - どの記録が残れば成功と言えるか。
69
+ - 応答を失った後の再送で、二度目の副作用が起きないか。取り消せないなら、何を保持して誰が照合するか。
70
+
71
+ コツ:
72
+
73
+ - 処理主体と保存先を分け、境界を越える要求と応答を同じ識別子で追うと、受付と完了の取り違えが見つかる。
61
74
 
62
75
  ### 4.4. 観測性と運用連携
63
76
 
64
- - 問い: 同じ処理を内外でどう照合するか。trace はどこまで渡せるか。採用しない場合は何を根拠に代替キーで追えるか。検知後に誰が何を止め、どこへ相談するか。
65
- - 具体化: イベントによる停止条件と、時間・滞留数などの監視条件を分ける。数値を使う場合は測定方法と判定時点を正本へ接続する。未決の通知方式・応答期限は追跡先へ渡し、異常・リスク・設計変更・人間の判断をどの管理記録へ引き渡すか整理する。
66
- - 対比: 「重複を検出して処理を停止し、OPS が取引 ID で外部受付と控えを照合、ARC へ照会し PM へ記録を渡す」なら動作と責任を分けられる。「runner が担当」では人間の次の手が決まらない。
77
+ 問い:
78
+
79
+ - 同じ処理を内外でどのキーで照合するか。trace を渡せない境界では何で追うか。
80
+ - 検知の後、誰が何を止め、どこへ相談するか。
81
+
82
+ コツ:
83
+
84
+ - 閾値を使うなら測定元と判定時点を正本に聞く。未決なら未決事項にし、無通知でよいとは書かない。
67
85
 
68
86
  ### 4.5. 関連ドキュメント導線
69
87
 
70
- - 問い: 設定正本のどの箇所と、どのテスト・復旧手順を読めば再現できるか。フローの統合・廃止を含む変更で、契約・schema・生成物・CLI・保存済み記録の互換性に何が波及するか。
71
- - 具体化: 受入条件ごとに実在するテストパスまたはテスト ID、実行方法、入力条件、期待結果、失敗判定を対応させる。内部・外部の結合境界を見分け、ITC/ETC のどちらへ引き渡すか考える。所在確認・網羅性確認・実行結果を分け、不足が受入・Schedule に与える影響と、担当・依存順・完了条件・判断時期・管理記録を結ぶ。
72
- - 対比: 「応答欠落のテストで売上一件と照合待ち表示を確認する。復旧手順の未整備は OPS が受入前に解消する追跡 ID へ渡す」なら検証と不足を分けられる。「テストファイルがあるので pass、運用は後で」では受入可否を判断できない。
88
+ 問い:
89
+
90
+ - どの設定とテスト・復旧手順を読めば、成功条件を再現できるか。
91
+ - フローの変更で、契約・保存済みの記録・CLI のどれに影響が及ぶか。
92
+
93
+ コツ:
94
+
95
+ - 設定値やテストの手順は写さず、所在への参照に置き換える。
73
96
 
74
97
  ## 5. 深掘り手順
75
98
 
76
- 1. 「失敗なら再試行」と書いた箇所を探し、受付前・受付後・保存後で結果が変わらないか分ける。
77
- 2. 図の非同期境界で応答を失った場合を追い、照合キーと保存記録が両側に残るか確認する。
78
- 3. 同じ ID を二つの実行へ与え、排他範囲や重複排除が本当に副作用を守るか問い直す。
79
- 4. 設定値を参照だけにした箇所を辿り、実効条件を一意に解決できなければ未決事項とする。閾値を使う判断では、測定元と判定時点が同じ条件を指すか確かめる。
80
- 5. 成功条件を一つずつ検証・運用の担当へ渡せる形にし、対応しない説明を削る。
99
+ 内容が浅いときは、次の順で対応のない主張を探す。
100
+
101
+ 1. 「再試行」「再開」の箇所ごとに、受付前・受付後・保存後で結果が変わらないかを確かめる。
102
+ 2. 図の非同期の境界で応答を失った場合を追い、照合キーと保存記録が両側に残るかを確かめる。
103
+ 3. 同じ ID を二つの実行へ与え、排他や重複排除が副作用を守るかを問い直す。
104
+ 4. 設定値の参照を辿り、条件を一意に解決できなければ未決事項へ移す。
105
+ 5. 成功条件ごとに検証・運用の担当へ渡せるかを確かめ、対応しない説明を削る。
81
106
 
82
107
  ## 6. 良い例 / 悪い例
83
108
 
84
- | 観点 | 良い例 | 悪い例・不足する判断 |
85
- | ---- | ------------------------------------------------------ | ------------------------------------------------ |
86
- | 再開 | 同じ block の最新状態を排他下で確認し、保持試行へ戻る | 時刻が来たら全件再実行。重複・所有権が不明 |
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
- | 適用境界 | CLI、API、ジョブ、生成、外部プロセス、保存先のどこが共通制約を持つか |
28
- | 正本 | 設定、schema、リファレンス、設計索引のどれが値と構造を決めるか。実在する検証コマンドと対象ケースへ進めるか |
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. **ルール一覧**: 同じ失敗を防ぐ制約をまとめ、ID と更新責務を付す。構成上の実行経路を横に並べ、エラー、冪等、時間・再試行、ログ・監査・追跡、秘密・権限、設定、モジュール境界の抜けを探す。確認待ちを先行する設定・契約の判断へ結び付ける。
38
- 3. **各ルール詳細**: 代表的な入力と途中失敗を追い、守る条件、防ぐ事故、適用境界、合否の観測、例外、正本を一組にする。検証する場所・コマンド・対象ケースを確かめ、実行結果と区別して記す。
39
- 4. **例外**: 過渡期の逸脱と未承認の不適合を区別する。期限・判断・復帰条件を決定記録へ接続し、不適合・リスク・変更を報告する人と追跡者を決める。
40
- 5. **関連導線**: 一つの規則変更から、実装・schema・生成物・互換性・移行・回帰対象までたどる。低レベル手順を本文に増やさず、担当と正本を接続する。
41
- 6. **未決事項と公開条件**: 確認できない事項を分離し、対象 ID・影響・判断者・期限・次アクションを揃える。実装適合の確認と人間による公開可否を分けて提示する。
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
- 良い例は「CLI と日次処理の失敗記録を共通化し、交代担当が再開対象を選べるようにする」。避けたい例は「API がないのでエラー・監視は対象外」で、代替の CLI の責務を消してしまう。
47
+ - 共通規則がないと、誰が同じ調査や回復を繰り返すか。
48
+ - 安全な保存と速度などが競合したとき、何を先に守るか。
49
+
50
+ コツ:
51
+
52
+ - HTTP API や DB がなくても、CLI のエラーやファイル保存の途中状態で同じ責務が残る。技術の不在を対象外の理由にしない。
53
+ - 上位の価値や背景を写したくなったら、上位成果物への参照に置き換える。
52
54
 
53
55
  ### 4.2. ルール一覧
54
56
 
55
- - 禁止・必須と要約を組み合わせても意図は変わらないか。
56
- - 一覧から詳細へ、詳細から確認担当・実装状況へたどれるか。
57
- - 先に設定や契約を決めなければ確認できない規則はどれか。確認群を使うなら全 ID が対応し、変更着手前・起動前・公開前のどこで確認するか分かるか。
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
- 良い例は「上限到達では部分出力を保持して停止し、受付結果を照合してから再開する」。避けたい例は「criticality に従い再試行する」で、区分・signal・上限が不明のままになる。Rule は不変条件へ絞り、確認手段は Enforcement にまとめる。
76
+ - 一つの途中失敗を、再試行・時間切れ・設定の競合・ログの欠落の順に追い、答えを適用境界と検証の説明に入れる。
77
+ - 上限値・設定キー・構文は写さず、正本への参照に置き換える。分からない値は推測で埋めず、実装担当に聞く。
80
78
 
81
79
  ### 4.4. 例外
82
80
 
83
- - 一時許可なのか、既に発生した問題なのか、将来の懸念なのか。
84
- - 例外の対象・期限が尽きたら誰が通常規則へ戻すか。
85
- - 決定記録と課題・リスク・変更の追跡先を区別できるか。
81
+ 問い:
82
+
83
+ - 一時的に許した逸脱か、既に起きた問題か、将来の懸念か。
84
+ - 期限が来たとき、どの検証で通常規則へ戻ったと判断するか。
86
85
 
87
- 良い例は「移行期間の対象 adapter のみ許可し、決定記録に期限と復帰の検証を付ける」。避けたい例は「緊急なら何でも許可」で、復帰できない。
86
+ コツ:
87
+
88
+ - 「緊急なら」など条件の広い許可を求められたら、対象の Rule と期限を具体的に聞き直す。
88
89
 
89
90
  ### 4.5. 関連導線
90
91
 
92
+ 問い:
93
+
91
94
  - 読む人はその参照で何を判断するか。
92
- - 参照先は現行・廃止・未作成のどれか。後継を一意に示せるか。
93
- - 見出し・表・参照ラベルで同じ文書を同じ名称で呼び、略号から正式名へ戻れるか。
94
- - schema 変更で古い記録・生成物・CLI 利用者に何が起きるか。
95
+ - schema を変えたとき、古い記録・生成物・CLI の利用者に何が起きるか。
96
+
97
+ コツ:
95
98
 
96
- 良い例は「DEV が schema と移行を更新し、旧形式の読込と再実行を検証する」。避けたい例は「関連文書一式を確認」で、更新と回帰の範囲が分からない。
99
+ - 見出し・表・本文で同じ文書を同じ名称で呼ぶ。略号だけでは参照先を特定できない。
100
+ - 参照先が未作成なら未作成と書き、作成済みのように扱わない。
97
101
 
98
102
  ### 4.6. 未決事項と公開条件
99
103
 
100
- - 不明な事実、意思決定待ち、仮定のどれか。
101
- - 誰がいつ判断し、解消しない間の受入・公開に何が制限されるか。
102
- - 計画・登録簿の実 ID がない場合、誰が次の計画更新で接続するか。
104
+ 問い:
103
105
 
104
- 良い例は「通知先は OPS が公開前に案を出し、PO が留保可否を判断。PM が未起票を接続する」。避けたい例は「OPD は後続で整備」で、判断と着手が浮いたままになる。
106
+ - 不明な事実か、意思決定待ちか、仮定か。
107
+ - 解消しない間、どの Rule の受入を止めるか。
105
108
 
106
- 情報の照合待ちは `_TODO_:`、意思決定待ちは `_UNDECIDED_:`、仮説は `_ASSUMPTION_:` を使って書き分ける。各論点を対象 Rule ID と結び、未発行の作業 ID は発行済みの証拠に数えない。
109
+ コツ:
110
+
111
+ - 不明は _TODO_、判断待ちは _UNDECIDED_、仮定は _ASSUMPTION_ で書き分ける。
112
+ - 未発行の作業 ID を、発行済みの証拠として数えない。
107
113
 
108
114
  ## 5. 深掘り手順
109
115
 
110
- 1. 一つの途中失敗を選び、残る変更・外部受付・利用枠から目的への影響を追う。無関係な実装解説を削る。
111
- 2. 同じ失敗の再実行と並列の別実行を追い、識別、重複防止、時間上限、停止、観測の途切れを見つける。実装された手段だけがあり、支える制約や防ぐ失敗を説明できない箇所も拾う。
112
- 3. 途切れた箇所の正本を確認し、根拠不足なら確認者と判断期限を付ける。便宜的な固定値で穴を隠さず、影響を受ける検証と受入判断へつなぐ。
116
+ 内容が浅いときは、次の順で対応のない主張を探す。
117
+
118
+ 1. 各 Rule が、概要のどの困り事を防ぐかを確かめ、対応のない実装解説を外す。
119
+ 2. 同じ失敗の再実行と並列の別実行を追い、識別・重複防止・時間上限・停止・観測が途切れる箇所を探す。
120
+ 3. 手段だけがあり、支える制約や防ぐ失敗を説明できない Enforcement を探す。
121
+ 4. 途切れた箇所の正本を確かめ、根拠がなければ固定値で穴を隠さず未決事項へ移す。
113
122
 
114
123
  ## 6. 良い例 / 悪い例
115
124
 
116
- | 観点 | 良い例 | 悪い例 |
117
- | ------ | ---------------------------------------------------------- | --------------------------------------- |
118
- | 冪等 | 同じ論理処理と attempt を区別し、保存・受付を照合して再開 | 同じファイル名へ書くので安全とする |
119
- | 検証 | 設定正本の上限直前・到達時を注入し、停止と保持状態で判定 | テスト名を列挙するだけ |
120
- | 設定 | 同じ項目の競合指定を与え、正本の優先順と反映時点を確認する | 全項目で CLI が優先すると推測する |
121
- | 観測 | 親子の識別子、保存先、秘匿化、確認者を結ぶ | ログがあるので運用可能とする |
122
- | 未整備 | 対象 ID と影響・判断者・期限・計画接続を示す | 存在しない OPD やタスクを発行済みと書く |
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
- - 値・構文・構造の再掲を正本参照へ置き換え、Rule と検証説明の反復を整理している。
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
- | 正本候補 | API・外部連携、保存・移行、モジュール境界、設定・実行構成、Job・定期処理、監視、ソース管理・CI の変更元はどこか |
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. 「SSOT 一覧(表形式)」の候補を、正本・派生物・業務記録・未確認に仕分ける。非該当は構成上の理由と代替正本、または代替不要の理由を確かめてから記入する。
38
- 3. 「自動生成物(生成コマンド/生成先/閲覧先)」で、設計の正本から再生成できる入力と出力を一対にする。script・サブコマンド、基準ディレクトリ、再生成する時機を照合する。
39
- 4. 「変更の入口(典型ケース)」で、集めた正本候補から代表的変更を選ぶ。最初の更新先から追従先、検証ケースまで一度たどり、非該当領域を導入する場合は構成判断も切り出す。
40
- 5. 「関連ドキュメント導線(C4 / NFR / OPD / DEC 等)」で参照目的を付け、現行・廃止・未作成を区別する。廃止文書は後継へ接続する。
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
- 範囲は機能・実行単位と、対象外になる境界から具体化する。良い例は「CLI と日次処理を対象に、DEV が更新、QE が失敗ケースを確認、PO が公開を承認する」。避けたい例は「全体を担当者が確認する」で、対象と責任の抜けを判断できない。
46
+ - どの利用者の、どの調査・引継ぎを助けるか。
47
+ - 対象外と、外部に任せる部分はどこか。
48
+
49
+ コツ:
50
+
51
+ - 範囲は機能や実行単位(CLI、日次処理など)で区切ると対象外が見える。外部に任せる部分は、連携の正本として残る。
52
+ - プロジェクトの背景は写さず、上位の文書への参照に置き換える。
52
53
 
53
54
  ### 4.2. SSOT 一覧
54
55
 
56
+ 問い:
57
+
55
58
  - 値を変えるとき、最初に編集するのはどのファイルか。
56
- - DB がない場合、保存形式と移行の契約はどこにあるか。
57
- - 監視は出力先だけでなく、形式・検知・通知を決める設定まで特定できるか。
58
- - モジュールの依存方向や統合条件を変える場合、境界の定義、ブランチ規約、CI・フック・検査 script のどれを更新するか。
59
+ - 「なし」と書く領域は、構成上ないのか、まだ調べていないのか。
60
+
61
+ コツ:
59
62
 
60
- 「なし」を使う前に、未確認か構成上の非該当かを問う。良い例は「RDBMS は非該当。保存レコード schema と移行処理を DEV が更新し、旧形式の読込を確認する」。避けたい例は「DB はなし」で、保存契約が索引から消える。代替も不要なら理由を確かめ、判断できなければ担当付きの _TODO_: とする。
63
+ - 開発担当に「この値を変えるとき最初にどこを開くか」と聞くと、派生物ではなく正本が出てくる。
64
+ - DB がない構成では保存形式と移行の契約が、監視では形式・通知を決める設定が抜けやすい。
61
65
 
62
66
  ### 4.3. 自動生成物
63
67
 
68
+ 問い:
69
+
64
70
  - 入力、コマンド、出力が実際につながっているか。
65
- - 生成後にどこを見れば更新を確認できるか。
66
- - 手編集が次の生成で失われるファイルを正本にしていないか。
67
- - 設計定義から再生成できる派生物か、取引・実行結果を保持する記録か。
71
+ - 生成後にどこを見れば更新を確かめられるか。
72
+
73
+ コツ:
68
74
 
69
- 出力名からコマンドを推測せず、既存の script と出力先を照合する。良い例は「契約変更時に API 定義から型を生成し、IDE と型検査で更新を確認する」。避けたい例は「ビルドで全ファイルを更新する」で、生成経路や業務記録との境界を確認できない。生成しない構成なら、その理由を短くまとめる。
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
- 分類は読み手の参照目的から選び、略語は初出時の説明と揃える。良い例は「運用方針・手順: 障害対応の判断に使う。索引は未作成のため、当面は現行の個別手順を参照し、OPS が整備後に接続する」。避けたい例は「関連: 運用一式、旧フロー」で、読む目的と現行性が分からない。
99
+ - 略号だけで分類すると、同じ文書を別名で呼び分けやすい。参照目的で分ける。
100
+ - 同名・後継・廃止の文書を取り違えやすい。
87
101
 
88
- ### 4.6. 未決事項・公開前確認
102
+ ### 4.6. 留保事項
103
+
104
+ 問い:
89
105
 
90
106
  - 不明な事実、意思決定待ち、仮定のどれか。
91
- - 何に影響し、いつまでに誰が判断するか。
92
- - 解消後にどの行・設定・手順へ反映するか。
107
+ - 解消したら、どの行・設定・手順へ反映するか。
108
+
109
+ コツ:
93
110
 
94
- 実装の検証結果と、非該当範囲・未整備の監視を留保して公開できるかの判断を分ける。良い例は「通知先は未決。OPS が検知要件を確認し、公開前に人間の PO が留保可否を判断、決定後に設定と手順を更新する」。避けたい例は「動いたので公開する」で、判断者と解消条件が抜けている。
111
+ - 実装が動いたことと、未整備の監視を残したまま使えるかは別の論点として分ける。
95
112
 
96
113
  ## 5. 深掘り手順
97
114
 
98
- 1. 一つの変更を選び、目的から正本、生成物、検証へ進む。到達しない箇所を情報不足として切り出す。
99
- 2. 非該当行を選び、代替の保存・連携・観測手段が索引から消えていないか確かめる。
100
- 3. 不在の参照や実行できないコマンドがあれば、推測で埋めず影響と担当を留保欄へ戻す。
115
+ 内容が浅いときは、次の順で対応のない主張を探す。
116
+
117
+ 1. 変更の入口の各行が、どの正本から始まり、どの検証で終わるかを確かめる。欠ける行は留保事項へ移す。
118
+ 2. 非該当の行ごとに、代わりの保存・連携・観測の手段が残っているかを確かめる。
119
+ 3. 自動生成物の各行の入力が、SSOT 一覧の正本にあるかを確かめる。ない行は正本か業務記録かを見直す。
101
120
 
102
121
  ## 6. 良い例 / 悪い例
103
122
 
104
- | 観点 | 良い例 | 悪い例 |
105
- | ---------- | -------------------------------------------------------------------- | ------------------------------------- |
106
- | パスの解釈 | 複数リポジトリの生成入力・出力に、それぞれの基準ディレクトリを添える | 同名の `src/` を基準なしで並べる |
107
- | 検証の範囲 | CI の検査成功と実機受入の未実施を分け、公開判断へ引き継ぐ | CI が成功したので運用も確認済みとする |
108
- | 改訂・廃止 | 旧正本の参照元を洗い出し、生成・検証・運用導線の更新を各担当へ渡す | 旧正本の行だけを削除して完了する |
123
+ | 観点 | 良い例 | 悪い例 |
124
+ | ---------- | ---------------------------------------------------------------- | ------------------------------------- |
125
+ | パスの解釈 | 複数リポジトリの入力・出力に、それぞれの基準ディレクトリを添える | 同名の `src/` を基準なしで並べる |
126
+ | 検証の範囲 | 「二つの実行が別の保存先を使うことを、分離テストで確かめる」 | 「代表実行が成功したので分離も確認」 |
127
+ | 検証の段階 | CI の検査成功と、実機での確認が未実施であることを分けて書く | CI が成功したので運用も確認済みとする |
109
128
 
110
129
  ## 7. レビュー観点
111
130
 
112
- | 観点 | 確認する問い |
113
- | ---------- | ----------------------------------------------------------- |
114
- | 所在 | 初めて読む DEV が正本を選べるか。派生物を選んでしまわないか |
115
- | 検証入力 | QE がコマンド・対象ケース・期待結果を一組で特定できるか |
116
- | 運用・承認 | OPS が設定と手順へ、PO が留保事項と承認条件へ到達できるか |
131
+ | 観点 | 確認内容 |
132
+ | -------- | ---------------------------------------------------------- |
133
+ | 所在 | 初めて読む開発担当が、派生物ではなく正本を選べるか |
134
+ | 検証経路 | 品質担当が、コマンド・対象ケース・期待結果を一組で選べるか |
135
+ | 委譲 | 値・電文・設定の中身を写さず、正本への導線だけを置いたか |
117
136
 
118
137
  ## 8. 仕上げチェック
119
138
 
120
- - 主な設計領域は所在または非該当理由と代替の要否に結び付き、未確認を確定情報にしていない。
121
- - 変更トリガーから更新先・追従先・期待結果をたどれ、詳細定義は正本に委ねている。
122
- - 現行文書のリンクと未作成のコード表記が区別され、判断待ちに担当と次アクションがある。
139
+ - 非該当の行に、代わりの手段か、代わりが要らない理由がある。
140
+ - 未確認の領域を確定情報にしていない。
141
+ - 実在しない文書やコマンドを現行の導線にしていない。