specdojo 0.8.0 → 0.9.1

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 (292) hide show
  1. package/.github/agents/specdojo-orchestrator.md +4 -1
  2. package/CHANGELOG.md +77 -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/orchestrator.js +5 -77
  9. package/dist/commands/where.js +25 -0
  10. package/dist/dashboard/dashboard.js +5 -3
  11. package/dist/dashboard/routines.js +4 -7
  12. package/dist/dashboard/shared.js +2 -2
  13. package/dist/dashboard/timeline.js +14 -14
  14. package/dist/deliverable/trash.js +2 -1
  15. package/dist/docs/index-command.js +2 -2
  16. package/dist/docs/yaml-business-tables.js +243 -0
  17. package/dist/docs/yaml-interface-tables.js +106 -0
  18. package/dist/docs/yaml-pages-command.js +5 -3
  19. package/dist/docs/yaml-pages.js +146 -3
  20. package/dist/docs/yaml-table-shared.js +70 -0
  21. package/dist/docs/yaml-tables.js +39 -0
  22. package/dist/exec/agent-config.js +9 -0
  23. package/dist/exec/agent-protected-config.js +2 -0
  24. package/dist/exec/commands.js +31 -18
  25. package/dist/exec/events.js +34 -14
  26. package/dist/exec/evidence.js +13 -3
  27. package/dist/exec/opencode-permissions.js +117 -0
  28. package/dist/exec/parent-validation.js +56 -3
  29. package/dist/exec/plans-core.js +21 -2
  30. package/dist/exec/plans-generation.js +6 -7
  31. package/dist/exec/post-integration.js +162 -0
  32. package/dist/exec/queue-command.js +166 -0
  33. package/dist/exec/queue.js +285 -0
  34. package/dist/exec/register-foreign-wait.js +82 -0
  35. package/dist/exec/repo-integration-sync.js +17 -5
  36. package/dist/exec/repo-trace.js +2 -1
  37. package/dist/exec/reporter.js +2 -2
  38. package/dist/exec/results.js +24 -4
  39. package/dist/exec/review-kata.js +4 -1
  40. package/dist/exec/run/agent-pipeline.js +3 -2
  41. package/dist/exec/run/agent.js +12 -6
  42. package/dist/exec/run/change-scope.js +365 -0
  43. package/dist/exec/run/deferred-cleanup.js +31 -0
  44. package/dist/exec/run/in-place.js +5 -2
  45. package/dist/exec/run/job-lock.js +66 -0
  46. package/dist/exec/run/job-sequence.js +137 -0
  47. package/dist/exec/run/job.js +56 -19
  48. package/dist/exec/run/lifecycle-commands.js +1 -1
  49. package/dist/exec/run/lock.js +22 -1
  50. package/dist/exec/run/register-command.js +8 -5
  51. package/dist/exec/run/register-mode.js +68 -8
  52. package/dist/exec/run/register-resume.js +68 -14
  53. package/dist/exec/run/register-state.js +13 -8
  54. package/dist/exec/run/register-worktree.js +140 -125
  55. package/dist/exec/run/schedule-mode.js +75 -14
  56. package/dist/exec/run/schedule-prepare.js +3 -0
  57. package/dist/exec/run/schedule-task.js +88 -38
  58. package/dist/exec/run/shared.js +5 -0
  59. package/dist/exec/schedule/schedule.js +116 -4
  60. package/dist/exec/shared.js +2 -2
  61. package/dist/exec/smoke.js +190 -0
  62. package/dist/exec/strategy.js +13 -3
  63. package/dist/exec/task-repos.js +19 -4
  64. package/dist/exec/task-view.js +6 -4
  65. package/dist/exec/trial-commands.js +5 -2
  66. package/dist/exec/trial-core.js +6 -1
  67. package/dist/exec/validation-metrics.js +181 -0
  68. package/dist/exec/worktree-cleanup-lock.js +26 -0
  69. package/dist/exec/worktree-command.js +12 -2
  70. package/dist/exec/worktree-ops-commit.js +2 -2
  71. package/dist/exec/worktree.js +13 -2
  72. package/dist/grade/command-apply.js +3 -3
  73. package/dist/grade/command-inspect.js +5 -3
  74. package/dist/grade/command-plan.js +1 -1
  75. package/dist/grade/command-run.js +5 -1
  76. package/dist/grade/run.js +64 -8
  77. package/dist/job/definition.js +84 -8
  78. package/dist/job/job.js +79 -23
  79. package/dist/register/authoring-sources.js +22 -16
  80. package/dist/register/maintenance-commands.js +2 -2
  81. package/dist/register/register.js +31 -7
  82. package/dist/register/renumber.js +1 -3
  83. package/dist/routine/definition.js +9 -0
  84. package/dist/routine/routine.js +137 -43
  85. package/dist/routine/status.js +62 -0
  86. package/dist/schedule/schedule.js +38 -39
  87. package/dist/shared/agent-types.js +5 -0
  88. package/dist/shared/cross-process-lock.js +9 -1
  89. package/dist/shared/dist-freshness.js +8 -2
  90. package/dist/shared/git-environment.js +2 -1
  91. package/dist/shared/git.js +44 -1
  92. package/dist/shared/lefthook-scaffold.js +3 -0
  93. package/dist/shared/local-config.js +244 -0
  94. package/dist/shared/specdojo-config.js +34 -20
  95. package/dist/shared/specdojo-gitignore.js +1 -0
  96. package/dist/shared/text.js +17 -1
  97. package/dist/shared/where-alias.js +13 -0
  98. package/dist/specdojo.js +4 -0
  99. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +2 -0
  100. package/docs/ja/specdojo/guides/exec-config-guide.md +23 -4
  101. package/docs/ja/specdojo/guides/exec-operation-guide.md +44 -1
  102. package/docs/ja/specdojo/guides/job-sequence-guide.md +77 -0
  103. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +1 -1
  104. package/docs/ja/specdojo/guides/quick-start-guide.md +3 -3
  105. package/docs/ja/specdojo/guides/register-operation-guide.md +1 -1
  106. package/docs/ja/specdojo/guides/routine-operation-guide.md +11 -6
  107. package/docs/ja/specdojo/guides/schedule-design-guide.md +20 -17
  108. package/docs/ja/specdojo/guides/waza-guide.md +12 -8
  109. package/docs/ja/specdojo/recipes/bac-recipe.md +66 -49
  110. package/docs/ja/specdojo/recipes/bes-recipe.md +90 -54
  111. package/docs/ja/specdojo/recipes/bps-recipe.md +88 -139
  112. package/docs/ja/specdojo/recipes/br-recipe.md +40 -47
  113. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +97 -109
  114. package/docs/ja/specdojo/recipes/cdfd-recipe.md +85 -146
  115. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +91 -110
  116. package/docs/ja/specdojo/recipes/cnd-recipe.md +79 -69
  117. package/docs/ja/specdojo/recipes/cpd-recipe.md +78 -64
  118. package/docs/ja/specdojo/recipes/cxd-recipe.md +92 -75
  119. package/docs/ja/specdojo/recipes/ifd-recipe.md +79 -68
  120. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +78 -105
  121. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +105 -71
  122. package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +60 -49
  123. package/docs/ja/specdojo/recipes/pm-members-recipe.md +50 -51
  124. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +59 -51
  125. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +69 -56
  126. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +37 -56
  127. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -53
  128. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +52 -79
  129. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +64 -93
  130. package/docs/ja/specdojo/recipes/prj-charter-recipe.md +71 -106
  131. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +78 -157
  132. package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +62 -111
  133. package/docs/ja/specdojo/recipes/prj-scope-recipe.md +67 -123
  134. package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +60 -96
  135. package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +61 -105
  136. package/docs/ja/specdojo/recipes/stsd-recipe.md +79 -109
  137. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +78 -55
  138. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +82 -73
  139. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +78 -59
  140. package/docs/ja/specdojo/recipes/tsd-recipe.md +149 -129
  141. package/docs/ja/specdojo/references/command-reference.md +258 -118
  142. package/docs/ja/specdojo/references/deliverables-reference.md +21 -12
  143. package/docs/ja/specdojo/references/specdojo-config-reference.md +47 -10
  144. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +101 -257
  145. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +102 -228
  146. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +19 -28
  147. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +16 -67
  148. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +30 -51
  149. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +41 -61
  150. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +22 -50
  151. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +24 -56
  152. package/docs/ja/specdojo/rulebooks/br-rulebook.md +13 -38
  153. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +41 -76
  154. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +18 -93
  155. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +18 -52
  156. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +109 -147
  157. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +80 -108
  158. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +21 -46
  159. package/docs/ja/specdojo/rulebooks/cdr-rulebook.md +144 -0
  160. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +27 -48
  161. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +37 -50
  162. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +52 -69
  163. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +33 -86
  164. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +16 -32
  165. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +45 -131
  166. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +69 -275
  167. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +20 -112
  168. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +23 -56
  169. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +12 -145
  170. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +39 -47
  171. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +37 -56
  172. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +118 -175
  173. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +5 -14
  174. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +22 -66
  175. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +36 -94
  176. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +59 -81
  177. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +31 -131
  178. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +50 -104
  179. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +51 -61
  180. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +38 -45
  181. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +14 -20
  182. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +26 -38
  183. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +26 -107
  184. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +42 -49
  185. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +14 -22
  186. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +21 -44
  187. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +41 -64
  188. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +14 -38
  189. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +34 -61
  190. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +27 -50
  191. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +70 -199
  192. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +65 -153
  193. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +74 -150
  194. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +11 -23
  195. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +99 -176
  196. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +35 -61
  197. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +75 -117
  198. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +31 -60
  199. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +26 -81
  200. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +32 -70
  201. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +45 -87
  202. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +48 -101
  203. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +44 -80
  204. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +59 -127
  205. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +31 -50
  206. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +42 -109
  207. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +29 -42
  208. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +29 -87
  209. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +62 -84
  210. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +11 -61
  211. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +91 -106
  212. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +25 -34
  213. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +30 -53
  214. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +23 -35
  215. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +27 -45
  216. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +37 -45
  217. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +45 -46
  218. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +37 -48
  219. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +25 -29
  220. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +28 -35
  221. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +36 -41
  222. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +5 -18
  223. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +16 -37
  224. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +23 -97
  225. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +39 -57
  226. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +43 -116
  227. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +16 -51
  228. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +47 -92
  229. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +25 -84
  230. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +44 -107
  231. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +39 -49
  232. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +42 -49
  233. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +64 -89
  234. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +90 -189
  235. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +45 -105
  236. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +6 -12
  237. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +49 -68
  238. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +51 -60
  239. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +46 -50
  240. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +39 -64
  241. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +47 -60
  242. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +69 -70
  243. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +65 -72
  244. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +35 -46
  245. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +49 -66
  246. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +64 -139
  247. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +41 -108
  248. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +49 -144
  249. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +67 -155
  250. package/docs/ja/specdojo/samples/bds-sample.md +58 -71
  251. package/docs/ja/specdojo/samples/bes-index-sample.md +20 -37
  252. package/docs/ja/specdojo/samples/bes-sample.md +43 -53
  253. package/docs/ja/specdojo/samples/bps-sample.md +42 -54
  254. package/docs/ja/specdojo/samples/br-sample.md +40 -52
  255. package/docs/ja/specdojo/samples/ccd-sample.md +0 -1
  256. package/docs/ja/specdojo/samples/cdr-sample.md +78 -0
  257. package/docs/ja/specdojo/samples/cdsd-sample.md +47 -63
  258. package/docs/ja/specdojo/samples/clis-sample.md +70 -77
  259. package/docs/ja/specdojo/samples/dec-sample.md +2 -3
  260. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +0 -2
  261. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +0 -2
  262. package/docs/ja/specdojo/samples/job-sequence.yaml +67 -0
  263. package/docs/ja/specdojo/samples/mip-index-sample.md +98 -20
  264. package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +26 -19
  265. package/docs/ja/specdojo/samples/pm-organization-sample.md +39 -50
  266. package/docs/ja/specdojo/samples/pm-plan-sample.md +61 -67
  267. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +31 -45
  268. package/docs/ja/specdojo/samples/pm-raci-sample.md +31 -37
  269. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +32 -48
  270. package/docs/ja/specdojo/samples/prj-charter-sample.md +42 -59
  271. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +55 -61
  272. package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +30 -33
  273. package/docs/ja/specdojo/samples/sf-index-sample.md +13 -55
  274. package/docs/ja/specdojo/samples/sf-sample.md +73 -85
  275. package/docs/ja/specdojo/samples/sld-sample.md +60 -79
  276. package/docs/ja/specdojo/samples/uis-sample.md +98 -121
  277. package/docs/ja/specdojo/standards/job-definition-standard.md +24 -9
  278. package/docs/ja/specdojo/templates/cdr-template.md +58 -0
  279. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +2 -1
  280. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +42 -5
  281. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +35 -0
  282. package/docs/specdojo/schemas/v1/job-run.schema.yaml +23 -0
  283. package/docs/specdojo/schemas/v1/job.schema.yaml +63 -2
  284. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +2 -2
  285. package/package.json +9 -6
  286. package/templates/antigravity/orchestrator.md +4 -1
  287. package/templates/claude/agents/specdojo-orchestrator.md +4 -1
  288. package/templates/codex/agents/specdojo-orchestrator.toml +4 -1
  289. package/templates/codex/orchestrator.md +4 -1
  290. package/templates/init-exec-defaults.yaml +13 -0
  291. package/templates/lefthook/tools/specdojo-pre-commit.mjs +8 -0
  292. package/templates/opencode/agents/specdojo-orchestrator.md +5 -2
@@ -11,48 +11,36 @@ specdojo:
11
11
 
12
12
  Comparison of Alternatives Writing Recipe
13
13
 
14
- 本ドキュメントは、代替案比較を「採択案、非採択案、技術的影響、見直し条件を説明できる内容」に仕上げるための作り方です。
15
- 本書では問い、深掘り手順、具体化のコツ、レビュー観点を扱います。
14
+ 代替案比較を、採択・非採択の理由と見直し条件を後から再現できる内容に仕上げるための作り方を示す。
16
15
 
17
16
  ## 1. このレシピの使い方
18
17
 
19
- - 最初に、スコープ、課題と解決アプローチ、前提・制約から、解くべき課題、必要能力、制約、評価条件を抜き出す。
20
- - 次に、意思決定を比較レイヤーへ分け、候補カテゴリと選定基準を決めてから具体候補を調査する。
21
- - 標準・方法論と製品・ツールを区別し、同じ意思決定を代替できる候補を各レイヤーで最低 2 案に広げる。
22
- - 最後に、採択、比較試行、保留、非採択、技術的影響、再評価条件を残し、判断の再現性を確保する。
23
- - 解くべき課題と必要能力(Why)、同じ意思決定と評価条件(What)、候補案・採択方針・軽減策(How)を整理し、決定 ID、課題 ID、評価理由、根拠資料、記録先で追跡する(Trace)。後続の設計詳細は比較結果から委譲する。
18
+ - 代替案比較は、課題と解決アプローチの課題・必要能力(Why)を引き継ぎ、決定 ID ごとに決めることと評価条件(What)を定め、候補案・採否・軽減策(How)を示す。採否は決定 ID・案 ID・課題 ID でたどれるようにする(Trace)。
19
+ - 「作成前に集める情報」をメモでそろえてから、「全体の作成手順」の順に書く。
20
+ - 書き終えたら「レビュー観点」で読み直し、「仕上げチェック」で確かめる。
24
21
 
25
22
  ## 2. 作成前に集める情報
26
23
 
27
- 最初から比較表を書かず、以下を短いメモで集める。
28
-
29
- | 項目 | 集める情報 |
30
- | -------------- | --------------------------------------------------------------- |
31
- | 比較目的 | 何を決めるための比較か、どの判断を支援するか |
32
- | 根拠資料 | スコープ、課題と解決アプローチ、前提・制約、関連する決定事項 |
33
- | 必要能力 | 課題を解くために必要な能力。特定の解決手段とは分けて集める |
34
- | 決定と順序 | 解決方式、購入 / 構築、製品など、先に決めることと後で決めること |
35
- | 代替案 | 同じ課題を解決できる一式の案 |
36
- | 比較レイヤー | 業務運用、解決方式、購入 / 構築、製品、開発方式など |
37
- | 候補カテゴリ | 非システム、汎用ツール、既存製品、個別構築など |
38
- | 候補選定根拠 | 公式資料で確認した責務、保管場所、対応環境、移行可能性 |
39
- | 評価軸 | 効果、コスト、期間、リスク、業務適合、技術実現性 |
40
- | 技術的成立条件 | 既存資産、外部依存、制約、後続成果物への影響 |
41
- | 採択判断者 | 最終判断を行う人間の責任ロール。通常は `PO` |
42
- | 再評価条件 | 方針を見直すトリガー、次に確認する指標、記録先 |
43
- | 正本・撤退条件 | 正しい情報源、同期方向、試行や外部ツールをやめる方法 |
24
+ 最初から比較表を書かず、次を短いメモで集める。
25
+
26
+ | 項目 | 集める情報 | 取り出し元 |
27
+ | ---------------- | ----------------------------------------------------------- | ------------------------------ |
28
+ | 課題と必要能力 | 解くべき課題の ID、課題を解くのに要る能力(手段とは分ける) | 課題と解決アプローチ |
29
+ | 範囲と対象外 | 比較に含める範囲、初期に優先する最小成立範囲、対象外 | スコープ |
30
+ | 制約と外部依存 | 予算・期間・端末・既存資産・判断責任の制約 | 前提・制約・依存関係 |
31
+ | 決めることと順序 | 先に決める判断と、その結果で要否が変わる判断 | 最終判断者への確認 |
32
+ | 候補と選定根拠 | 現行方式、外部の直接競合、責務・保管場所・移行可能性 | 公式資料、現場の担当者への確認 |
33
+ | 測れる値 | 操作時間、記録漏れ件数、費用など判定境界に使える実測値 | 現行運用の記録、試行 |
44
34
 
45
35
  ## 3. 全体の作成手順
46
36
 
47
- 1. H1 で比較対象の成果物名またはプロジェクト名を明示する。
48
- 2. 比較目的と前提条件で、決定 ID、判断順序、比較レイヤー、扱わない範囲を書く。
49
- 3. 前段文書から課題・制約・必要能力を抽出し、レイヤーごとの候補カテゴリと選定基準を定める。
50
- 4. 公式資料を調査し、現行方式、外部の直接競合、採用しない案を含む具体候補へ絞る。
51
- 5. 比較対象案で、同じ意思決定に属する候補を、ID、責務、強み、制約を揃えて並べる。
52
- 6. 評価軸と評価基準を比較レイヤーごとに定義し、同一レイヤー内では固定する。
53
- 7. 比較結果で、採択、一部採択、比較試行、保留、非採択と再評価条件を説明する。
54
- 8. 製品・サービスはデータの正本、移行、ロックイン、撤退方法を含めて技術的影響を示す。
55
- 9. リスクとトレードオフ、最終判断者、再評価条件、記録先を明示する。
37
+ 1. 比較目的と前提条件で、決定 ID と判断順序を先に決める。上位の判断(解決方式、購入 / 構築)が決まらないと、製品を比べる必要があるかが決まらない。
38
+ 2. 候補カテゴリと選定基準を定めてから、比較対象案を調べる。具体名から始めると、知っている製品だけが並ぶ。
39
+ 3. 評価軸と評価基準を、候補の評価より先に固定する。候補を見てから軸を選ぶと、結論に合わせた軸になる。
40
+ 4. 比較結果と採択理由を書き、技術的実現性と影響、比較試行の完了条件を添える。
41
+ 5. リスクとトレードオフに、採択案の不利な点と軽減策を書く。
42
+ 6. 決定と見直しに、採否の要約、最終判断者、再評価トリガー、記録先を書く。
43
+ 7. 最後に H1 直下の冒頭文を書く。採否が決まってから書くと、本文の言い直しにならない。
56
44
 
57
45
  ## 4. 各章の書き方
58
46
 
@@ -60,177 +48,110 @@ Comparison of Alternatives Writing Recipe
60
48
 
61
49
  問い:
62
50
 
63
- - この比較で、どの判断を支援するのか。
64
- - 業務運用、解決方式、購入 / 構築、製品、開発方式のどの比較レイヤーを扱うのか。
65
- - 対象プロジェクトの業務課題・利用者課題を直接解く判断になっているか。
66
- - 複数の判断がある場合、どれを先に決め、後続判断へ何を引き継ぐのか。
67
- - 比較対象に含める範囲と、含めない範囲は何か。
68
- - 根拠資料から引き継ぐ課題、必要能力、制約、評価条件は何か。
69
- - 根拠資料が示す対象外範囲や、初期段階で優先する最小成立範囲は、前提条件に引き継いでいるか。
51
+ - この比較で、どの判断を支援し、何を決めないのか。
52
+ - 複数の判断がある場合、どれを先に決め、後の判断へ何を引き継ぐのか。
70
53
 
71
- 書き方:
54
+ コツ:
72
55
 
73
- - 比較目的は 1〜2 文で書き、設計詳細や実装方式の説明に寄せすぎない。
74
- - 根拠資料は、直接判断に使う文書に絞る。
75
- - 未確定事項は _TODO_ / _UNDECIDED_ / _ASSUMPTION_ で明示する。
76
- - 対象外とする範囲や、全体を一度に完成させきれない場合の扱いがあれば、前提条件で明示する。
77
- - 複数レイヤーには `D-01` のような決定 ID を付け、各決定で扱わない範囲も書く。
56
+ - 最終判断者に「この比較が終わったら次に何を決めるか」を聞くと、判断の順序と決めないことが一度に分かれる。
57
+ - 課題や範囲の本文を写したくなったら、課題と解決アプローチ・スコープへの参照に置き換える。
78
58
 
79
59
  ### 4.2. 比較対象案
80
60
 
81
61
  問い:
82
62
 
83
- - 同じ目的を達成しうる案が最低 2 案あるか。
84
- - 各案の対象範囲は同じ粒度で説明できているか。
85
- - 各案は単独でも目的達成への道筋を説明できるか。
63
+ - 各案は、単独でも同じ課題を解く一式の案になっているか。
86
64
  - 現行案と根拠の異なる、採択しない可能性がある有力な外部案を含めたか。
87
- - 業務方式、製品、開発方式など抽象度の異なる候補を混在させていないか。
88
- - 具体候補より先に、候補カテゴリと選定基準を定めたか。
89
- - 「代表的」「標準」と呼ぶ根拠があるか。ない場合は比較候補と表現しているか。
90
-
91
- 書き方:
92
-
93
- - 案 ID は `ALT-01` のように安定した形式にし、複数レイヤーを扱う場合はレイヤーを識別できる prefix を使う。
94
- - 案名は手段だけでなく、優先する方針が分かる名前にする。
95
- - 対象範囲には、成果物、活動、機能、運用範囲を混在させすぎない。
96
- - 前段文書の案 ID を再掲する場合も、それだけで候補を閉じず、外部調査で得た候補を追加する。
97
- - 相互に組み合わせる要素は、業務運用を含む一式の解決案へまとめる。
98
- - 購入 / 構築の比較と具体製品の比較を分け、上位判断で必要性が残った場合だけ製品比較へ進む。
99
- - 開発戦略や作業管理は、プロジェクト運営そのものが比較目的の場合だけ主レイヤーにする。
100
- - 候補カテゴリは、非システム対応 / 汎用ツール / 既存製品 / 個別構築など、課題解決への道筋が異なる単位で分ける。
101
- - 公式資料から責務、データ保管、対応環境、移行可能性を確認し、市場占有率を調べていない候補を市場代表と断定しない。
65
+
66
+ コツ:
67
+
68
+ - 前段文書の案を並べ直すだけで終わりやすい。カテゴリ(非システム、汎用ツール、既存製品、個別構築など)ごとに 1 つ以上探す。
69
+ - 画面・データ・ツールなど組み合わせて使う部品を別案に分けたくなったら、業務運用を含む一式の案にまとめる。
70
+ - 市場占有率を調べていない候補は「代表」「標準」と呼ばず、比較候補と書く。
102
71
 
103
72
  ### 4.3. 評価軸と評価基準
104
73
 
105
74
  問い:
106
75
 
107
- - 評価軸は案ごとに変わっていないか。
108
- - 業務価値、意思決定、技術制約、リスクの観点が揃っているか。
109
- - 利用者適合、業務継続、データ移行、保守、将来変更を評価できるか。
110
- - `High` / `Middle` / `Low` の判定理由を説明できるか。
111
- - 評価軸は、根拠資料の課題 ID や業務価値のどの項目に対応するか説明できるか。
76
+ - 各評価軸は、どの課題 ID・制約から来ているか。
77
+ - `High` / `Middle` / `Low` の境界を、測定値または観察できる状態で言えるか。
112
78
 
113
- 書き方:
79
+ コツ:
114
80
 
115
- - 課題と制約を効果、コスト、期間、リスク、業務適合、技術実現性へ対応付ける。扱わない観点は観点名と不要な理由を、他軸へ統合する観点は対応先と判定条件を残す。
116
- - 重みを使う場合は、その理由と、優先順位か加重計算かの集約方法を書く。
117
- - 低いほどよい軸は、備考で判定方向を明示する。
118
- - 各軸に測定値または観察可能な状態で評価の境界を置く。未確認の値は未判定とし、確認作業を次の計画へ渡す。
119
- - レイヤーが異なれば評価軸を分けてよいが、同一レイヤーの候補には同じ軸と判定方向を使う。
120
- - 製品・サービスには、業務適合、データ移行、ロックイン、可逆性、成熟度を必要に応じて加える。
81
+ - 軸を省く・ほかの軸へ統合するときは、その場で観点名と理由、統合先と判定条件を書く。別章に書いたことを理由にすると、省いた妥当性を確かめられない。
82
+ - 「低いほどよい」軸(コスト・期間など)は、判定基準の列に有利な方向を書き込む。
83
+ - 値が確かめられない軸は未判定のまま残し、確かめる作業を比較試行へ回す。
121
84
 
122
85
  ### 4.4. 比較結果と採択理由
123
86
 
124
87
  問い:
125
88
 
126
- - 採択案は、どの評価軸で優位なのか。
127
- - 非採択案や一部採択案の理由は、再評価時に使える粒度か。
128
- - 比較試行と正式採用を区別し、試行の入力、評価軸、終了条件が決まっているか。
129
- - 技術的実現性と後続成果物への影響が読み取れるか。
89
+ - 採択案は、どの評価軸で他案より優れているのか。
90
+ - 比較試行を行う場合、同じ入力・測定項目・完了条件・撤退の基準は決まっているか。
130
91
 
131
- 書き方:
92
+ コツ:
132
93
 
133
- - 比較結果表の直後に、採択案と組み合わせ方を 1 文で書く。
134
- - 採択理由は評価軸に対応させ、同じ理由を複数の表と段落へ重複させない。
135
- - 技術的実現性と影響は、決定または案ごとの表にまとめて埋もれないようにする。
136
- - 比較試行では同じ入力と完了条件を使い、採用・撤退の判定と記録先を先に決める。
137
- - 製品・サービスを採択する場合は、データの正本、移行方法、利用停止時の取り出し方を書く。
94
+ - 採択理由を表の後の段落と決定の要約に重ねて書きやすい。理由は比較結果に 1 回だけ書き、ほかは参照する。
95
+ - 製品・サービスを採る場合は、データの正本、移行方法、利用停止時の取り出し方を担当者に聞いて書く。
138
96
 
139
97
  ### 4.5. リスクとトレードオフ
140
98
 
141
99
  問い:
142
100
 
143
101
  - 採択によって先送りする範囲、受容する負荷、失う選択肢は何か。
144
- - 起きうる失敗と軽減策は対になっているか。
145
- - 対象の決定・案 ID、担当 Role、依存作業、完了条件を PM が後続作業へ渡せるか。
102
+ - 軽減策を、誰が、何を確かめて終えるのか。
146
103
 
147
- 書き方:
104
+ コツ:
148
105
 
149
- - 区分は `リスク` / `トレードオフ` など少数に揃える。
150
- - 軽減策は「確認する」だけで終えず、何を残すか、誰が判断するかまで書く。
151
- - 技術詳細に踏み込む場合は、後続の設計成果物へ委譲する。
152
- - 軽減策や記録先の具体名称(計画書、登録簿等)は、根拠資料で存在が確認できる仕組みに限定する。根拠資料に存在しない計画書名・台帳名を新設せず、確認できない場合は「後続の品質確認」「成果物カタログと後続作業」のように確認済みの仕組みに言い換える。
106
+ - 軽減策を「注意する」「確認する」で止めず、実施者と完了の判定(差分 0 件など)まで聞く。
107
+ - 計画書・台帳の名前は、根拠資料で実在を確かめたものだけを書く。確かめられないときは「後続の品質確認」のように、確認済みの仕組みで言う。
153
108
 
154
109
  ### 4.6. 決定と見直し
155
110
 
156
111
  問い:
157
112
 
158
- - 現時点の採択方針は一文で言えるか。
159
- - 採択案の最終判断者が人間の責任ロールとして明記されているか。
160
- - どの条件で再評価し、どこに判断理由を残すか。
113
+ - 現時点の採否を、決定 ID ごとに 1 文で言えるか。
114
+ - どの期間・測定値・依存の変化で、比較をやり直すのか。
161
115
 
162
- 書き方:
116
+ コツ:
163
117
 
164
- - `PO` が最終判断し、AI Agent は比較分析の支援に留めることを明記する。
165
- - 再評価条件は、時間、指標、利用者フィードバック、依存変更など具体的なトリガーにする。
166
- - 方針変更時の記録先を、決定記録、変更要求ログ、プロジェクト登録簿などから選ぶ。
167
- - PM が追従を管理し、BA の業務影響、ARC の技術制約、DEV の実装、QE の受入・検証、PO の方針判断をどの更新へ接続するか確認する。
118
+ - 再評価トリガーを「特定製品が出たら採用」にしやすい。候補カテゴリ単位の条件に言い換える。
119
+ - AI Agent は比較分析の支援に留め、最終判断者の欄に入れない。
168
120
 
169
121
  ## 5. 深掘り手順
170
122
 
171
- 内容が浅いと感じる場合は、次の順で深掘りする。
123
+ 内容が浅いときは、次の順で対応のない主張を探す。
172
124
 
173
- 1. 比較目的を「何を決めるためか」に言い換える。
174
- 2. 前段文書から、課題、必要能力、制約、評価条件を抽出する。
175
- 3. 比較レイヤーごとに候補カテゴリと選定基準を定める。
176
- 4. 現行案から独立して、既存標準、方式、製品、ツールの公式資料を調査する。
177
- 5. 同じ意思決定を代替できる具体候補に絞り、標準・方法論と製品を区別する。
178
- 6. 評価軸を業務価値、費用、期間、リスク、運用、技術に分類する。
179
- 7. 評価軸を根拠資料の課題 ID や業務価値に対応付ける。
180
- 8. `High` / `Middle` / `Low` の根拠を 1 行ずつ補う。
181
- 9. 採択案の不利条件をトレードオフとして書く。
182
- 10. 採択・試行・保留・非採択の条件と、最終判断者、記録先、撤退方法を明示する。
125
+ 1. 各評価軸が、どの課題 ID・制約に結び付くかを確かめ、結び付かない軸を外す。
126
+ 2. 各案の判定が、どの軸の評価から導かれるかを確かめ、軸に現れない採択理由を見つける。
127
+ 3. 軽減策ごとに、どのリスクを抑えるかと完了の判定を確かめる。
128
+ 4. 再評価トリガーごとに、どの判定を覆すかを確かめる。
129
+ 5. 詳細設計・製品仕様を書きすぎた箇所を、後続成果物への参照に戻す。
183
130
 
184
131
  ## 6. 良い例 / 悪い例
185
132
 
186
- | 観点 | 良い例 | 悪い例 |
187
- | ------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------- |
188
- | 比較目的 | 販売・在庫・つけの記録を継続できる解決方式を選ぶ | どれがよいか考える |
189
- | 代替案 | 紙運用改善、既存サービス、個別構築を解決案として比較 | 画面、データ、開発ツールを別案として並べ、すべて採択する |
190
- | 比較レイヤー | 購入 / 構築を先に判断し、必要な場合だけ製品を比較 | 販売管理方式と開発タスク管理ツールを同じ表で採点 |
191
- | 候補選定 | カテゴリと基準を定め、各カテゴリの具体候補を公式資料で確認 | 知っている製品だけを代表例として比較 |
192
- | 評価軸 | 全案で同じ判定境界を使い、リスクを他軸へ統合するなら対応先と条件を記す | 案ごとに都合のよい観点だけを書く |
193
- | 採択理由 | 業務適合と記録継続を重視し、ALT-04 を採択する | ALT-04 がよさそうだから |
194
- | 技術影響 | タブレット 1 台で試行でき、ノート移行と紙への切り戻しを要する | 実現性や影響の根拠を書かずに結論だけ述べる |
195
- | 見直し条件 | 2 週間の試行で記録漏れが許容値を超えた場合、採択案を見直す | 必要なら見直す |
196
- | 試行 | 同じ販売・つけ記録を 2 候補で試し、操作時間と記録漏れを測る | 導入してから使いやすそうか判断する |
197
- | 軽減策の根拠 | 後続の品質確認で対応する(根拠資料にある仕組みを指す) | 品質管理計画で対応する(根拠資料に存在しない計画名を断定する) |
133
+ | 観点 | 良い例 | 悪い例 |
134
+ | ------------ | ----------------------------------------------------------- | -------------------------------------------------------- |
135
+ | 代替案 | 紙運用改善、既存サービス、個別構築を解決案として比較する | 画面、データ、開発ツールを別案として並べ、すべて採択する |
136
+ | 比較レイヤー | 購入 / 構築を先に判断し、必要な場合だけ製品を比較する | 販売管理方式と開発タスク管理ツールを同じ表で採点する |
137
+ | 軸の省略 | 「リスクは業務適合へ統合し、通信断時の記録保持で判定する」 | 「リスクは別章に書いたので評価しない」 |
138
+ | 試行 | 同じ販売・つけ記録を 2 候補で試し、操作時間と記録漏れを測る | 導入してから使いやすそうか判断する |
139
+ | 見直し条件 | 2 週間の試行で記録漏れが許容値を超えたら採択案を見直す | 必要なら見直す |
198
140
 
199
141
  ## 7. レビュー観点
200
142
 
201
- 作成後は、次の観点で確認する。
202
-
203
- | 観点 | 確認内容 |
204
- | -------------------- | ---------------------------------------------------------------------------------------------------- |
205
- | 比較目的の明確性 | 何を決めるための比較かが最初に分かるか |
206
- | 根拠資料との整合 | スコープ、課題と解決アプローチ、前提・制約と矛盾していないか |
207
- | 候補案の妥当性 | 最低 2 案あり、同じ目的を解ける案として並んでいるか |
208
- | 外部候補の網羅 | 前段文書の案の再掲だけでなく、既存標準・方式・製品を調査しているか |
209
- | 候補選定の再現性 | 候補カテゴリ、選定基準、公式資料が示され、特定製品へ恣意的に絞っていないか |
210
- | 比較レイヤーの統一 | 業務方式、製品、開発方式など抽象度が異なる候補を同じ表に混在させていないか |
211
- | 評価軸の一貫性 | 案ごとに評価軸や判定基準を変えていないか。根拠資料の課題 ID・業務価値に対応しているか |
212
- | 採択理由の説明可能性 | 採択、一部採択、非採択の理由が評価軸で説明されているか |
213
- | 技術的実現性 | 外部依存、既存資産、後続成果物への影響が読み取れるか |
214
- | 正本と可逆性 | 製品・サービスのデータ正本、移行、試行・採用からの撤退方法が読み取れるか |
215
- | 軽減策の実在性 | 軽減策や記録先が根拠資料で確認できる仕組みに基づいているか。未確認の計画書名・台帳名を作っていないか |
216
- | 人間の判断責任 | 採択案の最終判断者が `PO` など人間の責任ロールになっているか |
217
- | 再評価可能性 | 見直し条件と記録先が明記されているか |
143
+ | 観点 | 確認内容 |
144
+ | ------------ | ------------------------------------------------------------------------------ |
145
+ | 課題との対応 | 比較目的と評価軸が、課題と解決アプローチ・スコープの課題・範囲と食い違わないか |
146
+ | 候補の公平さ | 前段文書の案の再掲に留まらず、カテゴリごとに有力な外部案を調べているか |
147
+ | 判定の再現性 | 第三者が同じ判定境界で同じ判定にたどり着けるか |
148
+ | 正本と可逆性 | 製品・サービスを採る場合、データの正本と撤退方法が読み取れるか |
149
+ | 委譲の境界 | 詳細設計・製品仕様を後続成果物へ委ね、採否を左右する差異だけを残しているか |
218
150
 
219
151
  ## 8. 仕上げチェック
220
152
 
221
- - 「全体の作成手順」で示した章立てと必須表がそろっている。
222
- - 比較対象案が最低 2 案ある。
223
- - 各案が単独で目的達成への道筋を説明でき、同じ比較レイヤーにある。
224
- - 前段文書の候補案を名称変更して再掲するだけでなく、有力な外部案を調査している。
225
- - 候補カテゴリと選定基準を先に定め、根拠なく製品を代表・標準扱いしていない。
226
- - 業務運用、解決方式、購入 / 構築、製品、開発方式を必要に応じて分離している。
227
- - 開発戦略や作業管理を、業務課題と無関係に主比較へ持ち込んでいない。
228
- - 評価軸と評価基準が案ごとに固定されている。
229
- - 採択案、非採択案、一部採択案の理由が記載されている。
230
- - 評価軸が根拠資料の課題 ID や業務価値に対応している。
231
- - 技術的実現性と後続成果物への影響が比較されている。
232
- - 比較試行の条件と、製品・サービスのデータ移行・撤退方法が明確である。
233
- - リスクとトレードオフに軽減策がある。
234
- - 軽減策・記録先が根拠資料で確認できる仕組みに基づいている。
235
- - 採択案の最終判断者と再評価条件が明記されている。
236
- - 各採否を、解くべき課題、評価条件、評価結果、判断理由、再評価記録へ決定 ID から追跡できる。
153
+ - 各案の判定が評価軸の評価から導かれ、各評価軸が課題 ID・制約にたどれる。
154
+ - 省いた・統合した評価軸に、理由または統合先と判定条件が書かれている。
155
+ - 未確認の値を、確認済みの高評価にしていない。
156
+ - AI Agent を最終判断者にしていない。
157
+ - 個人名・個人の連絡先・公開できない組織情報がなく、役割名・集団名で書かれている。
@@ -11,42 +11,32 @@ specdojo:
11
11
 
12
12
  Project Issues and Approach Writing Recipe
13
13
 
14
- 本ドキュメントは、プロジェクト課題と解決アプローチを「関係者が、何が課題で、どれを、どう解く方針かを合意できる内容」に仕上げるための作り方です。
15
- 本書では問い、深掘り手順、具体化のコツ、レビュー観点を扱います。
14
+ プロジェクト課題と解決アプローチを、関係者が何が課題で、どれを、どう解く方針かを合意できる内容に仕上げるための作り方を示す。
16
15
 
17
16
  ## 1. このレシピの使い方
18
17
 
19
- - 最初に、プロジェクト概要・スコープ・前提制約から「何を実現したいか」と「成立条件」を短く抜き出す。
20
- - 次に、課題一覧、原因、解決策候補、採用アプローチと理由を順に書く。
21
- - 最後に、トレードオフ/リスクと次の検討事項を置き、未確定のまま判断を進めないようにする。
22
- - 目指す価値と課題の影響(Why)、優先課題と到達方針(What)、解決策候補・採用アプローチ・軽減策(How)を整理し、課題 ID、案 ID、根拠、採否理由、記録先で追跡する(Trace)。方式設計と実装詳細は後続成果物へ委譲する。
18
+ - 本書は、概要の目指す価値(Why)を引き継ぎ、優先課題と採用方針(What)を定め、解決策候補・採否理由・軽減策(How)を書く。課題 ID と案 ID で、課題から原因・候補・採否までたどれるようにする(Trace)。方式設計と実装詳細は書かない。
19
+ - 「作成前に集める情報」をメモでそろえてから、「全体の作成手順」の順に書く。
20
+ - 書き終えたら「レビュー観点」で読み直し、「仕上げチェック」で確かめる。
23
21
 
24
22
  ## 2. 作成前に集める情報
25
23
 
26
- 最初から正確に書こうとせず、以下を短いメモで集める。
27
-
28
- | 項目 | 集める情報 |
29
- | -------------- | -------------------------------------------------------------- |
30
- | 背景と必要性 | なぜ取り組むか、放置すると何が悪化するか |
31
- | 困っている現象 | 利用者や運用で実際に起きている問題(解決策ではなく現象) |
32
- | 影響 | 課題を放置した場合の損失、リスク、誰がどう困るか |
33
- | 原因の手がかり | 情報不足、判断基準の不在、手順のばらつき、システム制約など |
34
- | 解決の選択肢 | 取りうる方針(2 件以上)と、代替・補完の関係 |
35
- | 判断軸 | 効果、コスト、期間、リスク、再利用性、公開適性など重視する観点 |
36
- | 前提・制約 | スコープ、前提・制約・依存関係から、守るべき境界と成立条件 |
37
- | 未確定事項 | 追加調査、確認、承認が必要な事項と、その責任ロール |
24
+ | 項目 | 集める情報 | 取り出し元 |
25
+ | -------------- | ---------------------------------------------------- | -------------------------------------- |
26
+ | 目指す価値 | 誰のどの業務価値に近づけたいか、放置で何が悪化するか | プロジェクト概要 |
27
+ | 困っている現象 | 利用者や運用で実際に起きていること(解決策ではなく) | 利用者・運用担当への聞き取り、観察記録 |
28
+ | 境界と成立条件 | 対象範囲・対象外、守るべき前提・制約 | スコープ、前提・制約・依存関係 |
29
+ | 原因の手がかり | 確認できた事実と、まだ推測の段階のこと | 観察記録、既存の成果物、聞き取り |
30
+ | 判断軸の順序 | 効果・費用・期間・負荷などを、今回どの順で重視するか | 承認者への確認 |
38
31
 
39
32
  ## 3. 全体の作成手順
40
33
 
41
- 1. H1 で対象プロジェクト名を明示し、本書の目的(何が課題で、どれを、どう解く方針かを合意する材料)と利用ロール(PO は方針承認、BA は利用者影響整理、ARC は技術的境界識別、PM は作業計画入力など)、合意対象・非合意対象を 1〜2 段落で書く。
42
- 2. 課題一覧で、困っている現象、影響、優先度を書く。
43
- 3. 原因で、事実と仮説を分けて、課題ごとの発生要因を書く。
44
- 4. 解決策候補で、2 件以上の方針を概要、期待できる効果、対応課題、代替・補完の関係とともに並べる。
45
- 5. 採用アプローチと理由で、採用方針、補完策を組み合わせる理由、代替案の採否を判断軸で説明する。
46
- 6. トレードオフ/リスクで、捨てるもの・起きうることと軽減策を書く。
47
- 7. 次の検討事項で、未確定事項と責任ロールを書く。
48
- 8. 見直しと変更管理で、本書を見直す契機・確認観点・対応方針と記録先を書く。
49
- 9. 最後に、設計詳細や曖昧表現を書きすぎていないか確認する。
34
+ 1. 課題一覧を最初に書き、課題 ID を振る。原因と候補が課題 ID を参照するため、ここが決まらないとほかの章が書けない。
35
+ 2. 原因を、課題ごとに事実と仮説に分けて書く。
36
+ 3. 解決策候補を 2 件以上挙げ、代替か補完かと対応課題を添える。
37
+ 4. 採用アプローチと理由を、判断軸の順序に沿って書く。
38
+ 5. 必要な場合だけ、トレードオフ/リスク、次の検討事項(ToDo)、見直しと変更管理を書く。書く内容がなければ置かない。
39
+ 6. 最後に H1 直下の導入部(目的、承認者と利用ロール、合意対象と合意対象外)を書く。採用方針が決まってから書くと、本文の言い直しにならない。
50
40
 
51
41
  ## 4. 各章の書き方
52
42
 
@@ -55,120 +45,91 @@ Project Issues and Approach Writing Recipe
55
45
  問い:
56
46
 
57
47
  - 利用者や運用で、実際に困っている現象は何か。
58
- - 放置すると、誰が、どの業務価値で、どう困るか。
59
- - どの課題から先に決めるべきか(優先度)。
60
-
61
- 書き方:
62
-
63
- - 課題は「困っている現象」で書き、解決策の欠落(例:「自動発注がない」)にしない。
64
- - 各課題に最低限「影響」と「優先度」を添える。
65
- - 課題ID(例: P-01)を振り、原因表や決定記録から参照できるようにする。
48
+ - 放置すると、誰がどの業務価値で困るか。
66
49
 
67
- 良い例:
50
+ コツ:
68
51
 
69
- - 文書の粒度・構成・記述ルールがプロジェクトごとにばらつき、再利用・レビュー・引き継ぎが難しい。
70
-
71
- 悪い例:
72
-
73
- - 共通テンプレートがない。
52
+ - 「〜がない」と書き始めたら解決策の先取りなので、それがないと何が起きているかを聞き直す。
53
+ - 概要の背景を写したくなったら、概要への参照に置き換え、本書では課題の影響だけを書く。
74
54
 
75
55
  ### 4.2. 原因(仮説でも可)
76
56
 
77
57
  問い:
78
58
 
79
59
  - その課題は、なぜ起きているか。
80
- - 確認できている事実はどれで、推測はどれか。
81
- - 根拠となる文書や観察事実は何か。
60
+ - それは確認した事実か、まだ推測か。
82
61
 
83
- 書き方:
62
+ コツ:
84
63
 
85
- - 原因区分(事実 / 仮説)を明示し、混ぜない。
86
- - 課題IDで課題一覧と対応づける。
87
- - 根拠文書、観察事実、補足を添える。
64
+ - 仮説には、何を見れば確かめられるかを添えるよう聞く。確認方法がない仮説は、検証できないまま採否の根拠になりやすい。
65
+ - 一つの課題に原因を一つだけ書くと、候補が一つに絞られやすい。情報・判断基準・手順・制約の別に分けて聞く。
88
66
 
89
67
  ### 4.3. 解決策候補
90
68
 
91
69
  問い:
92
70
 
93
- - 課題を解くために取りうる方針は何か。
94
- - 候補同士は同じ判断を置き換える代替案か、別の課題・原因を扱う補完策か。
95
- - 各案は、どの業務価値に近づけるか。
96
- - 案ごとに失うもの・効果は何か。
71
+ - 候補は、同じ判断を置き換える代替案か、別の課題・原因を扱う補完策か。
72
+ - 各案は、どの課題に効き、何を失うか。
97
73
 
98
- 書き方:
74
+ コツ:
99
75
 
100
- - 2 件以上の方針を、案ID・関係・概要・期待できる効果・対応課題とともに並べる。
101
- - 単一案の押し付けにしない。
102
- - 案IDを振り、採用アプローチや代替案比較から参照できるようにする。
103
- - 同じ判断を置き換える案の詳細比較は代替案比較へ委譲し、本書では比較が必要な論点を示す。
76
+ - 案が一つしか出ないときは、「この案を採らないなら何をするか」と聞いて代替案を引き出す。
77
+ - 代替案どうしの詳細な比較を書き始めたら、比較が要る論点だけを残す。
104
78
 
105
79
  ### 4.4. 採用アプローチと理由
106
80
 
107
81
  問い:
108
82
 
109
- - どの案を採用し、補完策を組み合わせる場合は各案がどの課題・原因を担うか。
110
- - 各案を単独で採用した場合に不足することは何か。
111
- - 採用・非採用の判断軸は何で、今回重視する順序はどうか。
112
- - 採用しない案は、なぜ採用しないか。
83
+ - どの案を採用し、単独で採用した場合に何が不足するか。
84
+ - 採用しない案は、どの判断軸で外れたか。
113
85
 
114
- 書き方:
86
+ コツ:
115
87
 
116
- - 採用案を明記し、判断軸で採用理由を説明する。
117
- - 「採用対象」「判定」「理由」の表にすると、採否と根拠が読み取りやすい。
118
- - 補完策を組み合わせる場合は、併用する理由を説明する。中核・補助または実行順序がある場合だけ、その関係も示す。
119
- - 判断軸の優先順位を 1 文で示す。
88
+ - 判断軸の順序は承認者に先に聞く。順序が決まらないまま書くと、理由が「よさそう」に戻る。
89
+ - 補完策は、各案が担う課題・原因が重ならないかを確かめる。重なるなら代替の関係である。
120
90
 
121
91
  ### 4.5. トレードオフ/リスク
122
92
 
123
93
  問い:
124
94
 
125
- - 採用の代償として、何を捨てる・先送りする・我慢するか。
126
- - 起きうる失敗・遅延・品質低下は何か。
127
- - それぞれの軽減策は何か。
95
+ - 採用の代償として、何を捨てる・先送りするか。
96
+ - 起きうる失敗と、その軽減策は何か。
128
97
 
129
- 書き方:
98
+ コツ:
130
99
 
131
- - 区分(`トレードオフ` / `リスク`)で揃え、課題ログやリスク登録簿へ転記しやすい粒度にする。区切りの `/` の前後にはスペースを置かない。
132
- - リスクは「起きうること」と「軽減策」をセットで書く。
100
+ - 採用理由の判断軸で劣る点を探すと、トレードオフが見つかりやすい。
133
101
 
134
102
  ### 4.6. 次の検討事項(ToDo)
135
103
 
136
104
  問い:
137
105
 
138
- - 次の意思決定に必要な追加調査・確認・承認は何か。
139
- - それぞれの責任ロールは誰か。
106
+ - 次の意思決定に必要な調査・確認・承認は何で、誰が担うか。
107
+ - 何が決まれば完了で、いつまでに決める必要があるか。
140
108
 
141
- 書き方:
109
+ コツ:
142
110
 
143
- - 「ToDo」「目的」「責任ロール」の表にする。
144
- - ToDo の項目は、未確定事項を示す場合は _TODO_: または _UNDECIDED_ ラベルを先頭に付け、後続で検索・フィルタできるようにする(例: _TODO_: 公開先にGitHub を採用するか決定する)。
145
- - 責任ロールは、体制定義で採用済みのロールまたは担当単位で書く。
111
+ - 採否を保留した論点と、仮説の確認方法から拾うと漏れにくい。
146
112
 
147
113
  ### 4.7. 見直しと変更管理
148
114
 
149
115
  問い:
150
116
 
151
- - 本書の合意は、どんな変化で見直す必要があるか。
152
- - 見直したとき、何を確認し、どう対応するか。
153
- - 見直し結果は、どこに記録するか。
117
+ - どんな変化があれば本書の合意を見直すか。
118
+ - そのとき何を確認し、どう対応するか。
154
119
 
155
- 書き方:
120
+ コツ:
156
121
 
157
- - 見直しの契機(仮説の反証、スコープ・前提制約の変更、採用アプローチに影響する決定、リスクの顕在化など)を挙げる。
158
- - 契機ごとに、確認する観点と対応方針をセットで書く。
159
- - 記録先(プロジェクト登録簿、決定記録など)と、監視・取りまとめ・最終判断のロールを示す。
122
+ - 原因の仮説ごとに「反証されたら何を見直すか」を聞くと、契機と対応が対で決まる。
160
123
 
161
124
  ## 5. 深掘り手順
162
125
 
163
- 内容が浅いと感じる場合は、次の順で深掘りする。
126
+ 内容が浅いときは、次の順で対応のない主張を探す。
164
127
 
165
- 1. **困っている現象** を、解決策抜きで言い換える。
166
- 2. **影響** を、誰がどの業務価値で困るかで具体化する。
167
- 3. **原因** を、事実と仮説に分けて分解する。
168
- 4. **解決策候補** を 2 件以上に広げ、代替・補完の関係と対応課題を整理する。
169
- 5. **判断軸の優先順位** を決める。
170
- 6. **採用・非採用の理由** を判断軸で説明する。
171
- 7. **未確定事項と責任ロール** を残す。
128
+ 1. 各課題の影響が、目指す価値のどれに当たるかを確かめ、対応のない課題を外すか価値を問い直す。
129
+ 2. 各原因が課題 ID に結び付き、仮説に確認方法があるかを確かめる。
130
+ 3. 各候補が、どの課題・原因を扱うかを確かめ、対応先のない案を外す。
131
+ 4. 採否の理由が判断軸のどれによるかを確かめる。
132
+ 5. 設計詳細や特定技術の採否を書いた箇所を、後続の成果物への参照に戻す。
172
133
 
173
134
  ## 6. 良い例 / 悪い例
174
135
 
@@ -178,28 +139,18 @@ Project Issues and Approach Writing Recipe
178
139
  | 原因 | 事実: 担当ごとに記述様式が異なる / 仮説: 共通様式が浸透していない | なんとなく属人化している |
179
140
  | 解決策候補 | A 案と B 案は同じ課題への代替、C 案は別原因への補完と整理する | とにかく標準化する |
180
141
  | 採用理由 | A 案と C 案が異なる原因を扱い、単独では不足するため併用する | A 案がよさそうだから採用 |
181
- | リスク | 実践の型の整合が崩れる → 品質管理とレビューで確認する | 特に問題はない |
182
142
 
183
143
  ## 7. レビュー観点
184
144
 
185
- 作成後は、次の観点で確認する。
186
-
187
- | 観点 | 確認内容 |
188
- | -------------------- | ------------------------------------------------------------------ |
189
- | 業務価値との対応 | 課題と解決アプローチが、業務目的・利用者・期待効果と対応しているか |
190
- | 課題の妥当性 | 課題が困っている現象で書かれ、解決策の先取りになっていないか |
191
- | 事実と仮説の区別 | 原因で事実と仮説が混ざっていないか |
192
- | 候補の関係 | 方針が 2 件以上あり、代替・補完の関係と対応課題が明確か |
193
- | 採用理由の説明可能性 | 採用・非採用が判断軸で説明され、後から再現できるか |
194
- | 関係者・利用場面 | 関係者、利用場面、確認者、合意対象が読み取れるか |
195
- | 責務分担 | 設計詳細・実装詳細・テスト設計を書きすぎていないか |
196
- | 未確定の明示 | 未確定事項が _TODO_ / _UNDECIDED_ 等で明示されているか |
145
+ | 観点 | 確認内容 |
146
+ | ---------------- | -------------------------------------------------------------- |
147
+ | 業務価値との対応 | 課題と採用方針が、目指す価値・利用者・期待効果と対応しているか |
148
+ | 関係者・利用場面 | 承認者、利用ロール、合意対象が読み取れるか |
149
+ | 採否の再現性 | 後から読んだ人が、判断軸の順序から同じ採否を導けるか |
150
+ | 委譲の境界 | 設計詳細・実装詳細・特定技術の採否を書きすぎていないか |
197
151
 
198
152
  ## 8. 仕上げチェック
199
153
 
200
- - 「全体の作成手順」で示した章立てと必須表がそろっている。
201
- - 課題一覧、原因、解決策候補、採用アプローチと理由がすべて記述されている。
202
- - 解決策候補が 2 件以上あり、代替・補完の関係と対応課題がある。
203
- - 採用アプローチに判断軸と採用理由がある。
204
- - 各採用アプローチを、目指す価値、課題・原因、候補案、採否理由、見直し記録へ ID で追跡できる。
205
- - 曖昧表現や設計詳細を書きすぎていない。
154
+ - 各課題が原因・候補・採否まで課題 ID と案 ID でたどれる。
155
+ - 仮説を事実として書いていない。
156
+ - 課題・原因・リスクの記述に、個人や特定の組織を識別できる情報や非公開の観察事実がない。