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,187 +11,160 @@ specdojo:
11
11
 
12
12
  External Command Interface Specification Writing Recipe
13
13
 
14
- 外部 CLI とのプロセス境界を、実装の二重記述を避けて正本を参照し、入出力の約束(渡すもの・受け取るもの・終了コードの意味・作るファイル・副作用・失敗の扱い)に絞って合意・検証できる契約に仕上げるための作り方を示します。
14
+ 外部 CLI とのプロセス境界を、呼び出し元が成功・失敗を判定し、次の動作を一つに決められる契約に仕上げるための作り方を示す。
15
15
 
16
16
  ## 1. このレシピの使い方
17
17
 
18
- - ESIL(外部システム I/F 一覧)の連携目的を出発点に、呼び出し元が成功後に得る状態を決める。共通の背景は上位から引き継ぎ、この仕様ではプロセス境界の契約を具体化する。
19
- - 「作成前に集める情報」を短いメモにし、「全体の作成手順」の順で正本、入出力、終了判定、回復条件を決める。判断が止まった項目だけ「深掘り手順」で調べ直す。
20
- - 起動方法や設定値は設定・リファレンスへ、値・構文・構造の詳細は `docs/specdojo/schemas/v1/ifx-cmd.schema.yaml` へ委ねる。ここでは呼び出し元が判断するための意味と参照先の選び方を扱う。
21
- - 最後に ESIL の `spec_ref`、成功後の状態、観測信号、次の動作をたどる。実装が識別できない失敗や保証できない回復は、できることとして書かず、制約と確認先を残す。
18
+ - この仕様は、ESIL(外部システム I/F 一覧)の連携目的を引き継ぎ(Why)、呼び出し元が成功後に得る状態と入出力・終了状態の約束を定め(What)、識別信号・再試行・認証の渡し方を決める(How)。起動方法は正本の文書・設定キーへの参照で、仕様自体は ESIL の `spec_ref` からたどれるようにする(Trace)。
19
+ - 「作成前に集める情報」をメモでそろえてから、「全体の作成手順」の順に書く。判断が止まった項目だけ「深掘り手順」で調べ直す。
22
20
 
23
21
  ## 2. 作成前に集める情報
24
22
 
25
- | 項目 | 集める入力 | 判断に使う問い |
26
- | -------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
27
- | 連携目的と範囲 | ESIL の対象行、呼び出し元・連携先、方向、タイミング、`spec_ref` | 成功後に何が残れば目的を満たすか。別契約として分ける操作はあるか |
28
- | 正本と適用範囲 | 対象操作のリファレンス、起動設定のキー、対応バージョン、共通事項を持つ上位文書 | どの参照先が何を決めるか。複数 provider の差異もそこで解決できるか |
29
- | 起動方式 | 実行ファイルの解決方法、サブコマンド、シェル利用の根拠、設定の管理境界 | 実際の起動方式は何か。シェルを使うなら展開値の検証先はどこか |
30
- | ストリーム | stdin の要否と終端、stdout の受領範囲、stderr の用途、形式・文字コード | プロセス終了と業務完了を何で判定するか。進捗と構造化報告は混在するか |
31
- | ファイル | 入出力のパス解決規則、内容の正本、作成・更新主体 | CLI が変更する成果物と呼び出し元が保存する記録を分けられるか |
32
- | 終了状態 | 公開された終了コード、追加の検出信号と定義元、判定順、未分類時の扱い | 同じコードの失敗を区別できるか。識別できない原因は何か |
33
- | 副作用と再実行 | 永続的変更、利用枠消費、重複排除の根拠、失敗後に残る状態 | 再実行してよい条件は何か。保証がなければ何を確認して再開するか |
34
- | 認証と権限 | 認証方式、注入機構と参照名、必要権限、供給元、ログ保存境界 | 誰が認証状態を管理し、どの段階で何をマスクするか。秘密値自体は収集しない |
35
- | 制約と回復 | 作業ディレクトリ、時間・並列数・ネットワークの制約、再試行方針 | 上限は固定か設定依存か未決定か。子プロセス・部分出力・既存変更をどう扱うか |
23
+ | 項目 | 集める情報 | 取り出し元 |
24
+ | -------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
25
+ | 連携目的 | 呼び出し元と連携先、成功後に残る状態、別の契約に分ける操作 | ESIL の対象行、呼び出し元の担当者への確認 |
26
+ | 起動方法の正本 | 起動方法を決める文書・設定キー、対応バージョン、シェルを使う理由 | AI provider CLI は起動設定と exec 設定ガイド、ほかはコマンドリファレンス・公式資料 |
27
+ | 入出力 | stdin の内容と終端、stdout の採用範囲、stderr の用途、ファイルのパスと作成者 | 正本、実際の出力 1 回分、呼び出し元の実装担当への確認 |
28
+ | 終了状態 | 公開された終了コード、同じコードの失敗を分ける追加信号とその定義元 | 正本、検出信号を定義する設定 |
29
+ | 副作用と再実行 | 残る変更、利用枠の消費、途中失敗後に残る状態、重複を防ぐ手段 | 正本、運用担当への確認 |
30
+ | 認証 | 認証方式、渡し方、参照名、供給元、ログの保存先 | 認証を管理する担当への確認(秘密値そのものは集めない) |
31
+ | 制約 | 作業ディレクトリ、時間・並列数・ネットワークの上限と、固定・設定依存・未決定 | 起動設定、呼び出し元の実装担当への確認 |
36
32
 
37
33
  ## 3. 全体の作成手順
38
34
 
39
- 1. **連携単位とメタ情報**: ESIL の目的と成功後の状態を 1 文で対応させ、仕様 ID を `spec_ref` からたどれるようにする。目的・権限・出力契約が異なる操作は分け、複数 provider をまとめるなら共通契約の範囲を決める。
40
- 2. **`command`**: 対象操作の正本を選び、`reference` に文書・設定キー・適用範囲を示す。その根拠から実行ファイルの解決方法、起動方式、対応バージョンを記す。provider 一覧や引数表を別に作らない。
41
- 3. **`streams` と `files`**: 渡す内容、受け取る範囲、ファイルの解決規則と作成主体を整理する。成功を観測する信号と、後続処理が採用する内容を区別できたら次へ進む。
42
- 4. **`exit_codes`**: 正常・代表的失敗について、コードと追加信号からカテゴリへの判定順を組み立てる。区別できない原因には汎用失敗としての扱いを残す。
43
- 5. **`side_effects` と `execution.idempotency`**: 成功時と途中失敗時に残る変更・利用枠消費を確認し、重複排除の条件または保証できない理由と再開条件を記す。副作用の記述先は一つにまとめる。
44
- 6. **`authentication`**: 認証方式と渡し方、供給元、ログのマスク境界を整理する。参照名だけで利用対象を特定でき、秘密値を含まないことを確認する。
45
- 7. **`execution` と `error_handling`**: 制約の根拠を特定し、再試行の条件・上限・待機方式と、タイムアウト・出力解析失敗・認証失敗の処置を決める。未決定の制約は現在動作と必要な判断を分けて残す。
46
- 8. **分岐の照合**: 成功、同じコードの異なる失敗、出力欠落、途中失敗後の再実行を順に追う。各ケースの次の動作が一つに決まり、未確定項目の確認先を引き継げる状態で仕上げる。
35
+ 1. 連携単位を最初に決め、ESIL の目的と成功後の状態を 1 文で対応させる。目的・権限・出力が違う操作を混ぜたままだと、終了状態と副作用が一つに決まらない。
36
+ 2. `command` で起動方法の正本を決める。実行ファイル・引数・provider をどこまで書くかは、正本が何を持つかで決まる。
37
+ 3. `streams` と `files` で、成功を観測する信号と、後続処理が採用する出力を分ける。
38
+ 4. `exit_codes` を書く。前の手順で決めた観測信号が、同じコードの失敗を分ける材料になる。
39
+ 5. `side_effects` と冪等性を書く。途中失敗後に残る状態が分からないと、再試行してよいかを決められない。
40
+ 6. `authentication` を書く。
41
+ 7. `execution` と `error_handling` を最後に書く。終了状態と副作用が決まってから再試行の対象を選ぶと、回復の条件がない再試行を避けられる。
47
42
 
48
43
  ## 4. 各章の書き方
49
44
 
50
- YAML の各要素を、以下の判断単位として組み立てる。キーの必須性や型の一覧を作り直さず、呼び出し元が必要とする説明を該当要素へ置く。
51
-
52
45
  ### 4.1. 連携単位とメタ情報
53
46
 
54
47
  問い:
55
48
 
56
- - ESIL のどの連携目的を受け、呼び出し元の何を完了させるか。
57
- - 複数の操作や provider をまとめても、同じ成功条件で検証できるか。
58
- - 契約の改版と CLI の対応バージョンを混同していないか。
49
+ - 呼び出し元の何が終われば、この連携は成功か。
50
+ - 複数の操作や provider をまとめても、同じ成功条件で確かめられるか。
59
51
 
60
- 書き方:
52
+ コツ:
61
53
 
62
- - タイトルと実行目的を、対象と成功後の状態から書く。上位の背景説明を複製する代わりに、ESIL の対象行と仕様 ID の対応を確認する。
63
- - `based_on` は確認した直接の根拠から選び、カタログ管理下では依存関係の範囲内か調べる。起動方法の参照は `command.reference` に置き、根拠一覧へ機械的に転記しない。
54
+ - 「何が残れば成功か」を呼び出し元の担当者に聞くと、分けるべき操作が見つかる。
55
+ - 上位の背景説明を写したくなったら、ESIL の対象行への参照に置き換える。
64
56
 
65
57
  ### 4.2. コマンドと正本参照
66
58
 
67
59
  問い:
68
60
 
69
- - 起動方法と実行ファイルをどの文書・設定キーから解決するか。
70
- - provider が増えたとき、目的・実行ファイル・コメントの列挙を直さずに済むか。
71
- - 実際にシェルを使うか。使う理由、設定の管理者、展開値の検証・制限をどこで確認できるか。
61
+ - 起動方法を、どの文書・設定キーから解決するか。
62
+ - provider が増えたとき、この仕様のどこを直す必要があるか。
72
63
 
73
- 書き方:
64
+ コツ:
74
65
 
75
- - SpecDojo 自身のコマンドはコマンドリファレンス、AI provider CLI は起動設定と [[specdojo:exec-config-guide|exec 設定ガイド]]、その他の外部 CLI は対象操作の公式資料から正本を選ぶ。
76
- - `purpose` は成功後の状態に絞る。可変の実行ファイルは、たとえば `providers.<provider>.command_template` の先頭要素から解決する旨を `executable` に書き、provider 一覧は設定の鍵へ委ねる。認証対象の参照名など、別の判断に必要な情報まで削らない。
77
- - 通常の起動では実行ファイルとサブコマンドを分ける。管理された設定がシェルを必要とする場合は、理由と管理・検証の参照先を示して実態に合わせる。起動テンプレート全文や展開処理は転載しない。
66
+ - `executable` の括弧やコメント、`purpose` の括弧に provider 名を並べたくなったら書かない。一覧は起動設定の鍵が持ち、`executable` には先頭要素から解決する旨だけを書く。provider を足すたびに複数箇所を直すなら、写しが残っている。
67
+ - 一覧を削るときに、認証の参照名まで消しやすい。参照名は認証の対象を識別するのに要るので残す。
68
+ - シェルを使うかは、宣言ではなく実際の起動設定を見て確かめる。
78
69
 
79
70
  ### 4.3. ストリーム
80
71
 
81
72
  問い:
82
73
 
83
- - stdin は何を渡し、どこで入力終了となるか。使わない場合はどう表すか。
84
- - stdout 全体が構造化データか、それとも進捗と報告が混在するか。
85
- - stderr は何に使い、完了判定に使う信号とはどう区別するか。
74
+ - プロセスの終了と業務の完了を、それぞれ何で判断するか。
75
+ - stdout のうち、後続処理が採用するのはどこか。
86
76
 
87
- 書き方:
77
+ コツ:
88
78
 
89
- - 形式を実際のストリーム全体に合わせ、構造化部分だけを採用するなら抽出範囲と役割を書く。報告の詳細構造は正本を参照し、呼び出し元の判断に必要な意味を残す。
90
- - 終了コードが保証する範囲と、報告内容で確かめる完了条件を分ける。欠落・解析失敗時は「実行制約と失敗処置」につなげる。
79
+ - 構造化した報告が出るからといって、stdout 全体が構造化とは限らない。実際の出力を 1 回分見て、進捗が混ざるか確かめる。
80
+ - 報告の項目一覧は写さず、判断に使う意味だけを残す。
91
81
 
92
82
  ### 4.4. ファイル
93
83
 
94
84
  問い:
95
85
 
96
- - 入力・出力のパスはどのディレクトリを基準に、何から解決するか。
97
- - 各ファイルを作成・更新するのは CLI か、呼び出し元か、別段階の担当か。
98
- - 内容の詳細構造を持つ schema・仕様はどこか。
86
+ - 各ファイルのパスは、何を基準に何から決まるか。
87
+ - 各ファイルを作るのは CLI か、呼び出し元か。
99
88
 
100
- 書き方:
89
+ コツ:
101
90
 
102
- - `files.inputs` / `files.outputs` では、形式・文字コード・用途と可変パスの解決規則を組み合わせ、利用者が対象を特定できるようにする。
103
- - CLI が編集する成果物と、呼び出し元が保存するログ・報告を分けて説明する。後者を CLI 自身の生成物として数えず、内容のフィールド一覧は正本へ委ねる。
91
+ - 呼び出し元が保存するログや報告を、CLI の出力に数えやすい。作成者を実装担当に聞いて分ける。
104
92
 
105
93
  ### 4.5. 終了状態と識別条件
106
94
 
107
95
  問い:
108
96
 
109
- - 同じ終了コードを返す失敗は、どの追加信号で区別するか。
110
- - 複数の信号が一致したときの判定順と、どれにも一致しないときの動作は何か。
111
- - 認証失敗などを個別検出できない場合、誰が何を確認するか。
97
+ - 同じ終了コードを返す失敗を、どの追加信号で分けるか。
98
+ - どの信号にも一致しないとき、呼び出し元はどう動くか。
112
99
 
113
- 書き方:
100
+ コツ:
114
101
 
115
- - コードと信号を組み合わせて `meaning` を書き、カテゴリと `retryable` を対応させる。利用制限や接続失敗の検出条件は定義元を参照し、パターン一覧を複製しない。
116
- - 判断材料がない原因は断定しない。自動分類の範囲と手動確認の範囲を分け、exit 0 でも成果物の検証や業務完了には別条件があるか確かめる。
102
+ - 認証失敗などを個別に検出できない実装は多い。検出できない原因は断定せず、人が確かめる扱いにする。
103
+ - 検出パターンを写したくなったら、定義している設定への参照に置き換える。
117
104
 
118
105
  ### 4.6. 副作用と冪等性
119
106
 
120
107
  問い:
121
108
 
122
- - 成功時と途中失敗時に、外部状態・ローカルファイル・利用枠へ何が残るか。
123
- - 同一入力の再実行で重複処理を防ぐ根拠はあるか。
124
- - 保証できない処理を再開する前に、誰がどの状態を確認するか。
109
+ - 途中で失敗したとき、外部状態・ファイル・利用枠に何が残るか。
110
+ - 再実行の前に、誰が何を確かめるか。
125
111
 
126
- 書き方:
112
+ コツ:
127
113
 
128
- - `side_effects` には変更範囲、利用枠消費、変更してはならない境界をまとめる。別の配置を使う場合も同じ説明を二重に持たない。
129
- - `execution.idempotency` は保証の有無を先に判断し、保証するなら重複排除条件、しないなら理由と既存変更を引き継ぐ条件を書く。同名ファイルへの書き込みだけを保証の根拠にしない。
114
+ - 「同じファイルに書くから再実行しても安全」と考えやすい。利用枠の追加消費と、非決定的な編集の差分を聞いて確かめる。
130
115
 
131
116
  ### 4.7. 認証注入
132
117
 
133
118
  問い:
134
119
 
135
- - 認証の種類とプロセスへの渡し方はそれぞれ何か。既存ログイン状態を使うか。
136
- - 参照名から対象の環境変数・プロファイルを特定できるか。認証不要ならその判断根拠は何か。
137
- - 認証値の供給元と、引数・環境変数・stdout・stderr・保存ログの秘匿処理を誰が管理するか。
120
+ - 認証値は誰が用意し、どの経路でプロセスに渡るか。
121
+ - 引数・stdout・stderr・保存ログのどこで、誰がマスクするか。
138
122
 
139
- 書き方:
123
+ コツ:
140
124
 
141
- - `method` と `injection` を実際の認証経路に合わせる。`names` は利用対象を識別するために残し、実行目的などへ同じ対象一覧を複製しない。
142
- - `secret_source` に管理境界、`log_policy` にマスク対象と実施時点を書く。機構の参照名だけで説明し、秘密値や個人環境の認証パスは例にも使わない。
125
+ - 担当者には秘密値ではなく、仕組みと参照名だけを聞く。例にも実値や個人環境のパスを使わない。
143
126
 
144
127
  ### 4.8. 実行制約と失敗処置
145
128
 
146
129
  問い:
147
130
 
148
- - 作業ディレクトリ、時間、並列実行、ネットワークの制約を何から決めるか。
149
- - 再試行する失敗、回数の数え方、待機・切替・停止の条件は何か。
150
- - タイムアウト、出力解析失敗、認証失敗の後に、子プロセス・部分出力・既存変更をどう扱うか。
131
+ - 時間・並列数の上限は固定か、設定依存か、未決定か。
132
+ - タイムアウトや出力の解析失敗の後、子プロセス・部分出力・既存の変更をどう扱うか。
151
133
 
152
- 書き方:
134
+ コツ:
153
135
 
154
- - 確認した設定や公開契約から制約を記す。設定依存の値を固定値へ置き換えず、schema で表現できない場合は許容されるプレースホルダと共通ラベルで draft に残し、現在動作・必要な判断・次の確認先を記録する。
155
- - `retryable` と `retry.on_categories` を突き合わせ、副作用の回復条件を満たす場合だけ再試行につなげる。利用制限では短時間の制限と利用枠枯渇を区別し、細かな待機・切替方針は正本へ委ねる。
156
- - 三つの失敗処置は、停止する対象、保持・破棄するもの、次の確認者または再開条件から書く。上限や処置が未決定なら、現在の待機動作と決めるべき方針を混同しない。
136
+ - 上限が決まっていないとき、検査を通すために値を作りやすい。現在の動作と決めるべき判断を分け、_UNDECIDED_ で残す。
137
+ - 利用制限は、短時間の制限か利用枠の枯渇かを聞き分ける。待ち方が変わる。
157
138
 
158
139
  ## 5. 深掘り手順
159
140
 
160
- 1. **目的に戻る**: 説明できない制約や処置を一つ選び、それが防ぐ失敗と ESIL の目的への影響を確認する。目的につながらない内部処理の説明は削るか委譲する。
161
- 2. **正本をたどる**: 主張の根拠となる文書・設定キー・適用範囲を確認する。provider の追加や設定変更で複数箇所の修正が要るなら、一覧を正本へ戻し、実行ファイルの解決規則と認証の参照名など独立した判断情報は残す。
162
- 3. **分岐を再現する**: 曖昧なケースについて、入力、コード、追加信号、採用する出力、次の動作を短く並べる。同じ観測結果に複数の動作が残るなら、判定順を補うか自動分類の限界を書く。
163
- 4. **途中状態から追う**: 出力欠落や途中失敗を起点に、子プロセス、ファイル、外部状態、利用枠を確認する。再開に必要な確認・重複防止が説明できるまで、自動再試行の範囲を広げない。
164
- 5. **未確定を切り分ける**: 調査不足は _TODO_:、意思決定待ちは _UNDECIDED_:、仮の前提は _ASSUMPTION_: で分ける。現在動作、根拠、不足する判断、確認先を実行記録へ残し、架空の値で埋めない。
141
+ 内容が浅いときは、次の順で対応のない主張を探す。
142
+
143
+ 1. 各制約・処置が防ぐ失敗を挙げ、ESIL の目的に結び付かないものを外す。
144
+ 2. 各終了コードについて、入力・追加信号・次の動作を並べ、同じ観測結果に複数の動作が残る箇所を探す。
145
+ 3. 再試行の対象ごとに、副作用から回復する条件があるかを確かめる。
146
+ 4. 正本と同じ一覧・テンプレート・検出パターンを書いた箇所を、参照に戻す。
165
147
 
166
148
  ## 6. 良い例 / 悪い例
167
149
 
168
- | 判断単位 | 良い例 | 悪い例 |
169
- | ------------------ | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
170
- | 連携単位とメタ情報 | 発注登録の成功を受付番号の受領とし、在庫照会とは別の仕様 ID へ対応させる | 登録と照会を一つにまとめ、何が終われば成功か区別できない |
171
- | コマンドと正本 | `executable` は起動設定の先頭要素から解決し、provider 一覧は設定の鍵へ委ねる。`purpose` は成功後の状態を書く | 実行ファイル、目的、コメントに同じ provider 一覧を転載する |
172
- | シェル利用 | stdin を起動引数へ変換するためのシェル利用と、管理された設定・展開値の検証先を示す | 実際はシェル起動なのに `shell: false` とする、または外部 CLI という理由だけで有効にする |
173
- | ストリーム | stdout は進捗を含むテキストとし、末尾の構造化報告を抽出して完了状態を確認する | 構造化報告があるだけで stdout 全体を JSON とみなし、exit 0 だけで業務完了とする |
174
- | ファイル | CLI の編集対象は作業ディレクトリから解決し、runner が保存するログとは作成主体を分ける | 呼び出し元が保存するログも CLI が作るファイルへ含める |
175
- | 終了状態 | 非ゼロ終了と設定済み検出信号が一致した場合だけ利用制限とし、未一致は汎用失敗として停止する | exit 1 をすべて `transient_failure` にし、識別できない認証失敗まで自動再試行する |
176
- | 副作用と冪等性 | 非決定的な編集は冪等性を保証せず、差分を保持して確認後に再開する条件を書く | 同じファイルへ書くので再実行も安全だと判断し、利用枠の追加消費を無視する |
177
- | 認証注入 | ログインプロファイルの参照名と管理境界を残し、保存前のマスク対象を示す | 一覧の重複を削る際に認証対象まで不明にする、または秘密値・個人パスを例示する |
178
- | 実行制約と回復 | 時間上限が未決定なら現在は終了まで待つ事実と必要な判断を分け、出力異常後の変更保持と確認者を示す | 検査を通すためだけに固定上限を作り、失敗処置を「リトライする」で済ませる |
150
+ | 観点 | 良い例 | 悪い例 |
151
+ | ------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
152
+ | 連携単位 | 発注登録の成功を受付番号の受領とし、在庫照会とは別の仕様 ID にする | 登録と照会をまとめ、何が終われば成功か分からない |
153
+ | provider 一覧 | `executable` は起動設定の先頭要素から解決すると書き、`purpose` は成功後の状態だけを書く | `executable` の括弧、`purpose` の括弧、コメントに同じ provider 名を並べる |
154
+ | ストリーム | stdout は進捗を含むテキストとし、末尾の報告を取り出して完了を確かめる | 報告があるだけで stdout 全体を JSON とし、exit 0 だけで完了とする |
155
+ | 終了状態 | 非ゼロ終了と設定済みの検出信号が一致したときだけ利用制限とし、ほかは汎用失敗で止める | exit 1 をすべて一時失敗にし、識別できない認証失敗まで自動で再試行する |
156
+ | 失敗処置 | 出力の解析に失敗したら再試行を止め、変更を保持し、確認する人を示す | 「失敗時はリトライする」とだけ書く |
179
157
 
180
158
  ## 7. レビュー観点
181
159
 
182
- | 観点 | 確認方法 |
183
- | -------------------- | ---------------------------------------------------------------------------------------------------------- |
184
- | 目的と委譲境界 | 成功後の状態を ESIL の目的へたどり、API・ファイル・メッセージの詳細契約を重複して定義していないか確認する |
185
- | 正本への追跡 | 対象操作と設定キーから起動方法を解決し、provider 追加時に仕様内の一覧を複数更新する必要がないか試す |
186
- | 受領と生成の境界 | stdin から採用出力までを追い、進捗と報告、プロセス終了と業務完了、CLI の変更と呼び出し元の記録を区別する |
187
- | 分岐の実現性 | 同じコードの失敗を追加信号と判定順で追い、検出できない原因が手動確認へ進むか確かめる |
188
- | 回復の成立条件 | 途中失敗後の状態から再実行を追い、重複処理と利用枠消費を考慮した条件が再試行方針に反映されているか確かめる |
189
- | 認証の管理境界 | 参照名から供給元とマスク実施点を追い、秘密値を収集・転載せずに認証経路を説明できるか確認する |
190
- | 未確定事項の引き継ぎ | 固定値・設定依存・未決定を区別し、未決定項目から現在動作と次の確認先をたどれるか確認する |
160
+ | 観点 | 確認内容 |
161
+ | ---------- | ----------------------------------------------------------------------------- |
162
+ | 目的整合 | 成功後の状態が ESIL の連携目的とつながっているか |
163
+ | 回復 | 途中失敗後の状態から再実行を追い、二重処理と利用枠の消費を避ける条件があるか |
164
+ | 委譲の境界 | API・ファイル・メッセージの詳細や起動テンプレートを、正本と別に書いていないか |
191
165
 
192
166
  ## 8. 仕上げチェック
193
167
 
194
- - 「全体の作成手順」の分岐照合で曖昧さが解消されている。判断できない項目は現在動作・必要な判断・確認先を記録し、確定済みの記述へ混ぜていない。
195
- - 「作成前に集める情報」の入力と完成した契約を照合し、根拠のない固定値や、実際の起動方式・生成主体と異なる宣言が残っていない。
196
- - 本文・コメント・例を通して同じ一覧や説明を探し、判断を失わず正本参照へ置き換えられる重複を除いている。認証の参照名など独立した判断情報は残している。
197
- - 公開する本文・例・実行記録に秘密値、秘密値入り URL、個人環境の認証パスがなく、内部実装の説明は契約の参照に置き換わっている。
168
+ - 根拠のない固定値や、実際の起動方式・作成者と違う宣言が残っていない。
169
+ - 本文・コメント・例に、秘密値、秘密値入り URL、個人環境の認証パスがない。
170
+ - 未決定の項目は、現在の動作と次の確認先をたどれる形で残っている。
@@ -11,120 +11,154 @@ specdojo:
11
11
 
12
12
  External System Interface List Writing Recipe
13
13
 
14
- 外部連携の抜けと過剰な詳細化を避け、設計・実装・結合テストの担当が同じ連携対象を特定できる一覧へまとめるための手順を示す。
14
+ 外部連携の抜けと過剰な詳細化を避け、設計・実装・結合テストの担当が同じ連携対象を特定できる一覧へまとめるための作り方を示す。
15
15
 
16
16
  ## 1. このレシピの使い方
17
17
 
18
- - 上位の目的と対象範囲から、連携後に必要な結果を選ぶ。サービス名や採用ツールの列挙から始めない。
19
- - 境界の両端と受け渡しを整理し、連携目的・方向・方式・発生条件を YAML の各要素へまとめる。接続・認証・回復の詳細は契約へ渡す。
20
- - 連携名と `spec_ref` から後続の設計・結合テストへ追跡する。未整備の契約は、確認者・判断時点・保留する作業を整理して計画へつなぎ、人間の PO へ採否・公開の判断材料を渡す。
18
+ - 一覧は、上位の要求から連携が必要な理由(Why)を引き継ぎ、連携ごとの目的・両端・発生条件・異常時の判断(What)を定め、方向と方式(How)を境界の上で示す。連携名と `spec_ref` から詳細契約・結合テスト対象へたどれるようにする(Trace)。
19
+ - 「作成前に集める情報」をメモでそろえてから、「全体の作成手順」の順に書く。
20
+ - 書き終えたら「レビュー観点」で読み直し、「仕上げチェック」で確かめる。
21
21
 
22
22
  ## 2. 作成前に集める情報
23
23
 
24
- | 入力 | 集める内容 | 判断する問い |
25
- | ---------- | ----------------------------------------------------------- | ------------------------------------------------ |
26
- | 目的と範囲 | 対象業務・利用場面、連携が必要な結果、対象外 | 連携しなければ何が未完了になるか |
27
- | 境界と両端 | 自システム、外部サービス、CLI、受け渡すデータ | どこまでが自分たちの管理責任か |
28
- | 発生条件 | 人の操作、イベント、周期、前提状態 | 誰が何を確認した後に連携するか |
29
- | 正本の所在 | 詳細契約、設定、構文・データ構造の参照先 | 実在して対象操作へ対応しているか |
30
- | 失敗の影響 | 未完了・結果不明、外部変更、回復担当 | 再実行の前に何を照合する必要があるか |
31
- | 確認と合意 | 一覧の管理担当、承認・公開判断者、IF ごとの確認者と外部窓口 | 誰に何を確認すると採否や公開範囲を判断できるか |
32
- | 未完了作業 | 未決論点、担当 Role、判断時点、依存作業、Schedule・管理記録 | 何が決まらないとどの作業が進まず、誰へ報告するか |
24
+ | 項目 | 集める情報 | 取り出し元・聞く相手 |
25
+ | ------------ | -------------------------------------------------------- | ------------------------------ |
26
+ | 目的と範囲 | 対象の利用場面、連携しないと未完了になる結果、対象外 | 上位の要求・プロジェクトの範囲 |
27
+ | 境界と両端 | 自システム、外部サービス、起動する CLI、受け渡すファイル | 構成図、実装担当への確認 |
28
+ | 発生条件 | 人の操作、業務イベント、周期、起動の前提 | 業務の流れ、利用者への確認 |
29
+ | 詳細契約 | 対象操作に対応する詳細仕様の有無 | 外部 I/F 仕様の文書群 |
30
+ | 失敗の影響 | 未完了・結果不明になる結果、副作用を照合する担当 | 業務担当・運用担当への確認 |
31
+ | 確認者と論点 | 連携ごとの確認者と合意対象、外部側の窓口、未決の方式 | 確認の過程のメモ |
33
32
 
34
- 秘密値や個人環境の認証ファイルは収集しない。認証設計に必要な管理主体と方式の確認先だけを控える。
33
+ 秘密値や個人環境の認証ファイルは集めない。認証は管理主体と方式の確認先だけを控える。
35
34
 
36
35
  ## 3. 全体の作成手順
37
36
 
38
- 1. **対象範囲とメタ情報**: 対象システムと主要な対象外、管理担当と承認・公開判断者を冒頭コメントへ整理し、一覧を識別するタイトルと ID を決める。公開先と未合意の範囲を確認し、上位の背景は参照で引き継ぐ。
39
- 2. **連携単位**: 一つの利用場面を選び、境界を越える要求・データ・結果を追う。成功後の状態や失敗の影響を比べて分割を検討し、`interfaces` の各要素を結果が伝わる `name` で識別する。
40
- 3. **両端と方式**: `source` と `target` を固定してから `direction` を読む。自システムが API を直接呼ぶか、CLI やファイルを介するかを確かめ、`kind`・`format` と形式の内訳を記す。値域・構文は `docs/specdojo/schemas/v1/ifx-index.schema.yaml` を参照する。
41
- 4. **発生条件**: `timing` に起動イベントと前提状態を組み合わせる。「随時」を、利用者が判別できる条件へ置き換える。
42
- 5. **異常と参照**: `error_handling` に未完了・結果不明時の判断を残し、実在する詳細仕様と対象操作を照合して `spec_ref` へ接続する。未整備なら、解消する論点と影響する連携をコメントへ整理する。
43
- 6. **合意と計画**: IF ごとの確認者と合意対象、残作業と判断時点を整理する。連携名から Schedule の作業や PJR・決定記録へたどれるようにし、未登録なら PM への登録依頼と登録する時点をコメントへ残す。
44
- 7. **検証と引き継ぎ**: 一覧の schema・整形検査を実行した後、連携名から目的、契約、失敗時の確認先、保留範囲をたどる。検証結果と未解消事項を設計・実装・テスト担当へ渡し、採否・公開は人間の PO の判断へつなぐ。
37
+ 1. 冒頭コメントに対象範囲と対象外を書く。範囲が決まらないと、連携候補を入れるか外すか決められない。
38
+ 2. 利用場面を一つ選び、境界を越える要求・データ・結果を追って連携単位を切り出す。サービス名や採用ツールの列挙から始めると、目的のない行が混ざる。
39
+ 3. 連携ごとに `source` と `target` を先に決め、その後で `direction`・`kind`・`format` を選ぶ。両端が決まらないと方向が読めない。
40
+ 4. `timing` に発生条件を書く。
41
+ 5. `error_handling` に異常時の判断を書く。
42
+ 6. 詳細契約を対象操作と照らして `spec_ref` を決め、未整備や未決の論点をコメントに残す。
43
+ 7. 連携ごとの確認者と合意対象をコメントに書く。
44
+ 8. 最後に `id`・`title` を決める。対象範囲と連携がそろってからのほうが、一覧を識別できる名前になる。
45
45
 
46
46
  ## 4. 各章の書き方
47
47
 
48
- YAML の記入領域ごとに、次の問いを使う。
49
-
50
48
  ### 4.1. メタ情報と対象範囲
51
49
 
52
- - 何のシステム・利用場面の一覧か。将来案と現在の対象を区別できるか。
53
- - 一覧を維持する Role は誰か。人間の PO はどの範囲の承認・保留・公開可否を判断するか。文書の成熟度と個々の連携の合意を混同していないか。
54
- - 良い例は「店舗から本部への販売連携。仕入先連携は対象外」。避けたい例は「全外部システム」。範囲が読み取れる具体名を使う。
50
+ 問い:
51
+
52
+ - 何のシステム・利用場面の一覧か。
53
+ - 将来案と今の対象をどう区別するか。
54
+
55
+ コツ:
56
+
57
+ - 「全外部システム」のような範囲は、利用場面の具体名に置き換える。
58
+ - 上位の背景や目的を写したくなったら、上位成果物への参照に置き換える。
55
59
 
56
60
  ### 4.2. 連携単位と両端
57
61
 
58
- - 相手が同じでも、照会と更新で完了条件・失敗影響は異ならないか。
59
- - その行からどのデータ・結果を受け渡すか説明できるか。
60
- - 良い例は「商品照会」と「売上登録」を分ける。避けたい例は「本部連携」一行に全操作を詰める。製品名より結果を手掛かりに分ける。
62
+ 問い:
63
+
64
+ - 相手が同じでも、照会と更新で完了条件や失敗の影響は変わらないか。
65
+ - その連携で何を受け渡し、成功後にどんな結果を得るか。
66
+
67
+ コツ:
68
+
69
+ - 製品名ではなく、得る結果で分ける。名前も結果が伝わるものにする。
70
+ - 一つの行で回復の担当や完了条件が二つ出てきたら、分ける合図にする。
61
71
 
62
72
  ### 4.3. 方向・方式・形式
63
73
 
64
- - `source` と `target` に対して、どちらへ何が流れるか。要求と応答を同じ契約で扱うか。
65
- - 呼び出し境界は API、外部プロセス、ファイルのどれか。形式はストリーム全体を表すか。
66
- - 良い例は「印刷 CLI の入力テキストと結果 JSON をコメントで区別」。避けたい例は「結果の一部だけを見て全体を JSON とする」。
74
+ 問い:
75
+
76
+ - 自システムは API を直接呼ぶか、CLI を起動するか、ファイルを置くか。
77
+ - 形式は受け渡すストリーム全体を表しているか。
78
+
79
+ コツ:
80
+
81
+ - 実装担当に「自分たちのコードが何を起動するか」を聞くと、背後のサービスの方式と呼び出し側の方式を取り違えない。
82
+ - 結果の一部が JSON だからといって全体を JSON にしない。入力と結果の形式が違えば内訳をコメントで分ける。
67
83
 
68
84
  ### 4.4. 発生条件
69
85
 
70
- - 人の操作またはイベントのどの時点か。起動してはいけない前提不足は何か。
71
- - 再実行と初回実行で条件が変わるか。
72
- - 良い例は「会計確定と控え保存の後に印字」。避けたい例は「適宜印字」。具体的な固定時刻を推測して埋めない。
86
+ 問い:
87
+
88
+ - 誰の操作、どの業務イベントの後に連携するか。
89
+ - 起動してはいけない前提不足は何か。
90
+
91
+ コツ:
92
+
93
+ - 「随時」「適宜」と書きそうになったら、直前に何が終わっているかを聞く。
94
+ - 周期が分からないときは、固定時刻を推測で埋めない。
73
95
 
74
96
  ### 4.5. 異常時の判断
75
97
 
76
- - 応答がないとき、未処理か結果不明か。副作用を誰が照合するか。
77
- - その間に止める操作と維持する結果は何か。確認担当が何を照合できれば再開判断へ進めるか。
78
- - 良い例は「受付結果不明なら記録を保持し担当が照合」。避けたい例は「失敗なら即再送」。数値や引数表を増やさず、回復条件の正本を選ぶ。
98
+ 問い:
99
+
100
+ - 応答がないとき、未処理なのか結果不明なのか。
101
+ - 副作用を誰が照合し、その間どの操作を止め、どの結果を保つか。
102
+
103
+ コツ:
104
+
105
+ - 業務担当に「二重に登録・印字されたら何が困るか」を聞くと、再送してよいかが分かる。
106
+ - 引数や再試行の数値を書きたくなったら、回復条件の正本への参照に置き換える。
79
107
 
80
108
  ### 4.6. 詳細参照と未決事項
81
109
 
82
- - 詳細契約は実在し、この操作の成功・結果不明時の判断へ対応するか。参照先があっても残る未決事項は何か。
83
- - 未整備なら、誰が何を確認・決定すれば接続できるか。解消条件と期限または判断するマイルストーンは何か。決まるまでどの業務・後続作業・公開範囲を保留するか。
84
- - コメントを書く際は、作成・確認待ちを `_TODO_:`、意思決定待ちを `_UNDECIDED_:`、仮定を `_ASSUMPTION_:` で整理する。良い例は「`spec_ref: TBD` とし、ARC が DEV と結果照合方式を決め、外部結合テスト着手前に QE が期待結果を確認するまで当該連携の受入を保留」。避けたい例は「契約は後で作る」。論点から解消後の次アクションまでをつなぐ。
110
+ 問い:
85
111
 
86
- ### 4.7. 合意・計画・課題への引き継ぎ
112
+ - 詳細契約はこの操作の成功・結果不明の判断に対応しているか。
113
+ - 決まるまで、どの連携の受入や後続作業を保留するか。
87
114
 
88
- - BA に利用場面・業務影響、ARC・DEV に契約、QE に期待結果の何を確認してもらうか。外部側の確認が必要なら窓口は誰か。未特定なら誰がいつ特定するか。
89
- - 詳細仕様の未着手・作成中・確認待ちのどこで止まっているか。担当 Role、完了条件、判断時点、依存作業は計画のどこから確認できるか。
90
- - 未決論点や方式変更は、どの連携・後続仕様・Schedule に影響するか。PM へどの作業・課題の登録をいつ依頼し、PO へ何の判断と保留範囲を報告するか。
91
- - 良い例は「売上登録の認証未合意を、PM が結合テスト計画確定前に PJR へ登録し、着手条件と PO の判断を追跡する」。避けたい例は「関係者確認済み」。合意対象と残作業をコメントから管理記録へ結び、登録後は実在する作業・レコードへの参照へ付け替える。
115
+ コツ:
92
116
 
93
- ### 4.8. 検証と引き渡し
117
+ - 文書 ID があるだけで対応を確かめずに `spec_ref` へ入れやすい。対象操作の記述まで開いて照らす。
118
+ - 詳細契約があっても残る論点は、`spec_ref` で解決済みにせずコメントに残す。
94
119
 
95
- - 対象 YAML に schema・整形検査を実行し、対象ファイル、コマンド、結果を記録したか。失敗箇所を直した後の再実行まで追えるか。
96
- - 検査では分からないコメントの内容や参照先を、読み手は連携名から確認できるか。目的・両端・方向・詳細契約を一つの利用場面として説明してもらう。
97
- - 良い例は「検査成功と、売上登録の合意待ちによる受入保留を分けて引き継ぐ」。避けたい例は「schema が通ったので公開する」。未解消事項には担当と次アクションを添えて判断者へ渡す。
120
+ ### 4.7. 合意と計画への引き継ぎ
121
+
122
+ 問い:
123
+
124
+ - 利用場面・業務影響、契約、期待結果を、それぞれ誰に確かめてもらうか。
125
+ - 外部側の確認が要るなら、窓口は誰か。
126
+
127
+ コツ:
128
+
129
+ - 「関係者確認済み」で済ませず、何について合意したかを聞く。
130
+ - 計画の期日や進捗を写したくなったら、計画や管理記録への参照に置き換える。
98
131
 
99
132
  ## 5. 深掘り手順
100
133
 
101
- 1. 一つの利用場面について、連携がなくても同じ結果を得られるかを問う。必要性を説明できなければ範囲の判断へ戻す。
102
- 2. 正常応答と応答欠落を追い、同じ行の中で異なる回復担当・完了条件が現れたら契約の分割を検討する。
103
- 3. 未決事項から影響する後続作業を逆にたどる。判断者・確認窓口が不明なら特定する作業へ、期限が決められないなら依存するマイルストーンの確認へ分解する。
104
- 4. 方式変更や連携の追加・廃止を一件仮に当てはめる。旧名との対応、詳細契約、DEV の実装対象、QE の結合テスト対象を追い、対象範囲が変わるなら PO へ何を確認するか整理する。
134
+ 内容が浅いときは、次の順で対応のない主張を探す。
135
+
136
+ 1. 各連携について、連携がなくても同じ結果を得られるかを確かめ、目的に対応しない行を外すか範囲の判断へ戻す。
137
+ 2. 各連携の方向と方式が、両端の間の同じ受け渡しを表しているかを確かめる。
138
+ 3. 異常時の判断ごとに、照合の担当と止める操作が決まっているかを確かめる。
139
+ 4. 未決事項ごとに、影響する連携と保留する後続作業を逆にたどる。たどれない論点は、どの連携の論点かを決め直す。
105
140
 
106
141
  ## 6. 良い例 / 悪い例
107
142
 
108
- | 観点 | 良い例 | 悪い例 |
109
- | ------------ | ------------------------------------------------------------ | ---------------------------------------- |
110
- | 仮定と合意 | CLI 経由案は仮定とし、採否・公開条件を PO に確認する | 技術案の採用で外部公開も承認済みとする |
111
- | 未決の出口 | 認証方式の決定後、DEV が契約を作成し QE が着手条件を確認する | 認証は後で決める |
112
- | 変更の追跡 | 連携の分割元と影響する契約・テスト対象を対応づける | 改称後の一覧だけを渡し、旧契約を放置する |
113
- | 管理への接続 | 連携コメントから Schedule の作業と残論点をたどれる | 一覧に期日・進捗表をコピーして別管理する |
143
+ | 観点 | 良い例 | 悪い例 |
144
+ | ---------- | ------------------------------------------------------------ | ---------------------------------------- |
145
+ | 連携単位 | 「商品照会」と「売上登録」を分ける | 「本部連携」一行に全操作を詰める |
146
+ | 発生条件 | 「会計確定と控え保存の後に印字」 | 「適宜印字」 |
147
+ | 異常時 | 「受付結果不明なら記録を保持し担当が照合」 | 「失敗なら即再送」 |
148
+ | 未決の出口 | 照合方式が決まるまで売上登録の受入を保留する、とコメントする | 「契約は後で作る」 |
149
+ | 変更の追跡 | 分割元の連携名と影響する契約・テスト対象を対応づける | 改称後の一覧だけを渡し、旧契約を放置する |
114
150
 
115
151
  ## 7. レビュー観点
116
152
 
117
- | 観点 | 確認する内容 |
118
- | -------------- | ---------------------------------------------------------------------------------------- |
119
- | 必要性と範囲 | 各連携が対象の目的へ結び付き、将来案と対象外を識別できるか |
120
- | 境界の一貫性 | 両端、方向、方式、形式が同じ受け渡しを表すか |
121
- | 下流への接続 | 連携名から契約と失敗時の確認先へ到達し、変更後の実装・結合テスト対象を選べるか |
122
- | 合意と判断 | IF ごとの確認者・合意対象と、人間の PO に残る採否・公開判断の範囲を説明できるか |
123
- | 委譲と未決事項 | 詳細を重複管理せず、論点から担当・解消条件・判断時点・保留する作業へたどれるか |
124
- | 計画と管理 | 残作業やリスクが Schedule・PJR・決定記録へつながり、未登録なら PM への依頼時点が分かるか |
153
+ | 観点 | 確認内容 |
154
+ | ------------ | ------------------------------------------------------------------ |
155
+ | 必要性と範囲 | 各連携が対象の目的に結び付き、将来案と対象外を区別できるか |
156
+ | 境界の一貫性 | 両端、方向、方式、形式が同じ受け渡しを表しているか |
157
+ | 下流への接続 | 連携名から詳細契約と失敗時の確認先へ着き、結合テスト対象を選べるか |
158
+ | 委譲の境界 | 引数・設定値・計画の期日を写さず、参照に置き換えているか |
125
159
 
126
160
  ## 8. 仕上げチェック
127
161
 
128
- - 作成前に集めた利用場面と一覧を突き合わせ、未記載の連携候補は対象外または判断待ちとして理由を説明できる。
129
- - 各章の問いで得た回答が同じ連携を指し、例にある担当・判断時点を実案件の確認なしで転用していない。
130
- - 検証記録と引き継ぎ内容が一致し、確認待ちを解消済みと扱わず、次の担当が着手条件を選べる。
162
+ - 集めた利用場面と一覧を突き合わせ、載っていない連携候補を対象外または判断待ちとして説明できる。
163
+ - 各節の問いへの答えが同じ連携を指し、例の担当や条件を実案件の確認なしで転用していない。
164
+ - 確認待ちの連携を解消済みと扱っていない。