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,196 +11,216 @@ specdojo:
11
11
 
12
12
  Technology Stack Detail Definition (TSD) Writing Recipe
13
13
 
14
- 採用した技術や実行基盤について、別の担当者が構成を再現し、利用できる状態か判断できる文書へ仕上げる手順を示します。初期構築、クライアント接続、日常利用の違いを整理し、設定の根拠から確認・復旧までをつなぎます。
14
+ 採用した技術や実行基盤を、別の担当者が対象環境で再現し、利用できる状態か判断できる文書に仕上げるための作り方を示す。
15
15
 
16
16
  ## 1. このレシピの使い方
17
17
 
18
- - 上位設計や非機能要件から、対象の技術で実現する利用場面と守る条件を短く抜き出す。技術一覧の採用理由や組織全体の運用方針は、その正本への参照で引き継ぐ。
19
- - 「作成前に集める情報」をメモし、「全体の作成手順」で一冊の担当範囲を決める。初期構築・接続・日常利用をまとめるか分けるかは、読み手の開始条件と設定の更新単位から判断する。
20
- - 「各章の書き方」を使い、構成、採用値、反映操作、正常性の判定を具体化する。必要な設定例やコマンドは対象環境で再現できる粒度にし、内部クラス、詳細 API 仕様、SQL 全文の設計はその担当文書へ委ねる。
21
- - 最後に、利用目的に対する採用設定、設定を反映する操作、確認結果の対応をたどる。文書 ID、設定項目名、確認項目名で根拠を追跡し、未実施の確認は残る作業として示す。
18
+ - TSD は、上位設計・非機能要件が求める利用場面と品質条件(Why)を引き継ぎ、採用する設定値と到達状態(What)を定め、導入・接続・確認・復旧の操作(How)で実現する。設定項目名と確認項目名で、採用値から反映操作と確認結果までたどれるようにする(Trace)。
19
+ - 「作成前に集める情報」をメモでそろえてから、「全体の作成手順」の順に書く。
20
+ - 書き終えたら「レビュー観点」で読み直し、「仕上げチェック」で確かめる。
22
21
 
23
22
  ## 2. 作成前に集める情報
24
23
 
25
- 秘密値を収集せず、次の問いに答える短いメモを作る。確認不足は _TODO_、意思決定待ちは _UNDECIDED_、仮の前提は _ASSUMPTION_ を付け、担当と確認・判断の時期を添える。
24
+ 秘密値は集めない。確かめられない点は _TODO_、決まっていない点は _UNDECIDED_、仮に置いた前提は _ASSUMPTION_ を付けてメモに残す。
26
25
 
27
- agent に作成を任せる場合は、集めた情報や前提をどこに渡すかを決める。成果物の外から継続して渡す共通前提はカタログの `brief`、起票時や対話で決まった前提・調査選定の委任は個票の `入力`(`--input`)、成果物の特定章に対する具体的な指示は雛形内の `_CONTEXT_:` に書く。
26
+ | 項目 | 集める情報 | 取り出し元 |
27
+ | ------------------ | ------------------------------------------------------------------ | -------------------------------------------- |
28
+ | 利用目的 | 誰が何をできるようにするか、応える責務と品質条件 | 上位設計、非機能要件 |
29
+ | 文書の境界 | 技術一覧・基盤定義・接続設定・利用手順のどこに正本があるか | 技術一覧、既存の TSD |
30
+ | 環境と権限 | 実行場所ごとの OS、ランタイム、ユーザー、権限、依存の版、資源 | 対象環境での確認、構築担当者への確認 |
31
+ | 配置と経路 | プロセスの配置、通信方向、待受と接続先のアドレス、公開範囲 | 構成図、ネットワーク設定 |
32
+ | 設定の事実 | 導入済みの版、有効な設定値、保存先、優先順位、再起動の要否 | 対象環境での表示・照会の結果 |
33
+ | 採用の判断 | 決定済みの値と推奨候補、互換性・ライセンス・資源の制約 | 決定記録、公式情報、技術選定の担当者への確認 |
34
+ | 認証の仕組み | 認証方式、秘密の取得・保存・注入の方法、固有の接続先を公開できるか | 基盤の管理者への確認 |
35
+ | 確認の記録 | 最小の利用成功、期待結果、確認した環境・版・日付 | 確認の実行記録 |
36
+ | 継続利用と変更影響 | 切断・再起動・再構築で残る状態、旧方式との競合、撤去で失う状態 | 対象環境での試行、運用担当者への確認 |
28
37
 
29
- | 入力 | 答える問い・集める情報 | 主な文脈の置き場所 |
30
- | ------------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
31
- | 利用目的と根拠 | 誰が何をできるようにするか。上位設計のどの責務・品質条件に応えるか | カタログの `brief` または個票の `--input` |
32
- | 文書の境界 | 技術一覧、既存の基盤定義、接続設定、利用手順のどこに正本があるか | カタログの `brief` または第 1 章(概要・位置づけ)の `_CONTEXT_:` |
33
- | 環境と権限 | OS、実行環境、ユーザー、権限、依存の版、必要な CPU・メモリ・ディスクは何か。特別な条件がない項目はどれか | カタログの `brief`(共通基盤条件)または第 2 章(対象環境・前提条件)の `_CONTEXT_:` |
34
- | 配置と経路 | 接続元、ホスト、コンテナ、サービスはどこで動き、どの方向へ通信するか。公開範囲はどこまでか | 第 3 章(全体構成・接続経路)の `_CONTEXT_:` または個票の `--input` |
35
- | 設定の事実 | 導入済みの版、有効な設定、保存先、優先順位、再起動の要否を何で確認できるか | 第 5 章(導入・初期設定)の `_CONTEXT_:` または個票の `--input` |
36
- | 採用の判断 | 決定済みの値と推奨候補は何か。互換性、ライセンス、資源の制約と採否の根拠は何か | カタログの `brief`(決定方針)または第 4 章(採用技術・設定)の `_CONTEXT_:`・`--input` |
37
- | 認証と公開範囲 | 認証方式、秘密情報の取得・保存・参照の仕組みは何か。固有の接続先や識別子を公開できるか | 第 6 章(接続設定と秘密情報の扱い)の `_CONTEXT_:` または個票の `--input` |
38
- | 確認と証跡 | 最小の利用成功は何か。確認場所、期待結果、確認環境・版・日付、記録先は何か | カタログの `done_criteria`(完了条件)または第 7 章(動作確認)の `_CONTEXT_:` |
39
- | 継続利用と変更影響 | 切断、再起動、再構築で何が残るか。旧方式との競合、切り戻し、撤去で失う状態は何か | 第 8 章(継続利用・運用)・第 10 章(更新・復旧・撤去)の `_CONTEXT_:` |
40
-
41
- ### 2.1. 文脈の置き場所の使い分けの目安
42
-
43
- - **カタログの `brief`**: プロジェクトや成果物群で共通する技術スタック・基盤前提(例: 「静的サイト構成とし、主流の技術スタック(Astro 等)を採用する」)。YAML アンカーで複数成果物へ共有できる。
44
- - **個票の `入力`(`--input`)**: 起票時や対話で決まった前提、または agent に技術スタックの調査や選定を任せる範囲(例: `--input "静的サイトで主流の技術スタックを調べて選定する"`)。
45
- - **成果物内の `_CONTEXT_:`**: `deliverable scaffold --project <project-id> --target <doc-id>` で生成した雛形の各章見出し直下に書く局所的な指示(カタログにない成果物は `--target-path` と `--target-rulebook` を指定。例: 第 4 章で `_CONTEXT_: 主流のフレームワークを比較し、選定理由と採用値を提案してください`)。`draft` が本文へ反映後に削除する。
38
+ agent に技術の調査や選定を任せる場合は、任せる範囲を起票時の入力に書き、特定の章への指示は雛形のその章に書く(例: 「採用技術・設定」に `_CONTEXT_: 主流のフレームワークを比較し、選定理由と採用値を提案してください`)。
46
39
 
47
40
  ## 3. 全体の作成手順
48
41
 
49
- 1. 利用目的を一文にし、文書を読み始める人の状態と、読み終えて確認する到達状態を書き出す。独立した利用目的が混ざっていたら別文書へ分ける。
50
- 2. 初期構築・接続設定・日常利用の担当を決める。同じ読み手が同じ前提で一続きに作業し、設定を一か所で保守できるなら一冊にまとめる。構築済み基盤を複数のクライアントが利用する、または接続・再開だけを繰り返すなら分冊を選ぶ。分冊ごとに前提の文書と開始できる確認結果をメモする。
51
- 3. 対象が分かる `tsd-<term>.md` の名前と配置を決め、既存文書との重複を確かめる。各設定の正本を一つ決め、別冊側ではその完了条件と本書で変える差分を示す。CLI で雛形を作成する場合は `specdojo deliverable scaffold --project <project-id> --target <project-id>:tsd-<term>`(カタログにない成果物は `--target-path` と `--target-rulebook` を指定)を実行する。TSD の rulebook(`specdojo:tsd-rulebook`)は `template: not-needed` だが、`deliverable_type: architecture` を引き継いだ最小構成の雛形が生成される。
52
- 4. 章の下書きを「概要・位置づけ」「対象環境・前提条件」「全体構成・接続経路」「採用技術・設定」「導入・初期設定」「接続設定」「動作確認」「継続利用・運用」「制約・トラブルシュート」「更新・復旧・撤去」「参照情報」の流れで置く。対象に応じて章を統合・並べ替え、扱わない手順は対象外とする理由や委譲先を概要へ残す。
53
- 5. 接続元・ホスト・コンテナなどに呼び名を付け、配置と通信方向を図か表にする。各操作の実行場所、設定保存先、権限をこの呼び名へそろえる。
54
- 6. 採用設定を表にし、推奨候補や任意の選択肢と分ける。実測・決定・公式情報のどれを根拠にしたか確かめ、裏付けがない版や容量は決めた値として埋めない。
55
- 7. 導入、設定変更、接続の順序を組み立てる。設定を追加・部分変更・全体置換する範囲と、既存設定を残す方法、反映に必要な操作を各段階へ添える。
56
- 8. 基盤の起動から最終利用まで確認を段階化し、各確認に期待結果と失敗時の戻り先を書く。設定の有効値の確認は、単なる疎通確認と分ける。
57
- 9. 切断・再接続・再起動・再構築の違いを調べ、必要な再開操作と失われる状態を書く。移行や撤去を扱う場合は、旧方式との共存可否、切り戻し、保持するデータを先に決める。
58
- 10. 本文、設定例、出力例を公開可否の観点で読み直す。秘密値は参照方法へ、機密の固有情報はプレースホルダーへ置き換える。
59
- 11. 「レビュー観点」と「仕上げチェック」で、別の担当者が開始条件から正常性の判定まで進めるか確認する。未確認の条件には残る確認方法を付け、成功した事実と区別して仕上げる。
42
+ 1. 利用目的を一文にし、読み始める人の状態と、読み終えて確認する到達状態を書き出す。独立した目的が混ざっていたら、ここで別文書へ分ける。ほかの章の範囲はこの到達状態で決まる。
43
+ 2. 初期構築・接続設定・日常利用を一冊にまとめるか分けるかを決める。同じ読み手が同じ前提で一続きに作業するならまとめ、構築済みの基盤へ複数のクライアントが接続する、または接続と再開だけを繰り返すなら分ける。
44
+ 3. 接続元・ホスト・コンテナに呼び名を付け、「全体構成・接続経路」を先に描く。以降の章で実行場所と保存先をこの呼び名でそろえられる。
45
+ 4. 「対象環境・前提条件」に、呼び名ごとの環境と権限を書く。
46
+ 5. 「採用技術・設定」で採用値を決め、推奨候補・任意の選択肢・未決と分ける。
47
+ 6. 「導入・初期設定」「接続設定と秘密情報の扱い」で、採用値を反映する順序を組み立てる。
48
+ 7. 「動作確認」を基盤の起動から最終利用まで段階に分け、各段階の失敗が戻る先を決める。
49
+ 8. 「継続利用・運用」「更新・復旧・撤去」に、切断・再起動・再構築・移行の影響を書く。
50
+ 9. 「制約・トラブルシュート」を、動作確認の失敗先から症状別に組み立てる。動作確認を先に書くと、症状と確認箇所が対応する。
51
+ 10. 「参照情報」に、採用判断と手順の根拠を集める。
52
+ 11. 最後に「概要・位置づけ」を書く。担当範囲と別冊の開始条件は、ほかの章が決まってから書くと実態とずれない。
53
+ 12. 本文・設定例・出力例を公開できるか読み直す。
60
54
 
61
55
  ## 4. 各章の書き方
62
56
 
63
- 以下は下書きを具体化するための順序である。各章を独立させるか、関連する章へまとめるかは、読み手が行う作業に合わせて選ぶ。
64
-
65
57
  ### 4.1. 概要・位置づけ
66
58
 
67
- - 問い: どの利用目的に応え、初期構築・接続・日常利用のどこを扱うか。読み手が既に完了している作業は何か。
68
- - 書き方: 目的、対象、対象外を短く置き、別冊へ進む境界にその開始条件を添える。既存文書は project 修飾 doc id の `[[id|title]]` 形式で参照し、未作成なら `tsd-<term>.md` のような仮のファイル名で示す。
69
- - 良い例: 「構築済み基盤へ接続するクライアントの設定を扱う。基盤側の起動と利用対象の登録確認を開始条件とし、本体の導入は基盤定義へ委ねる」。避けたい例: 「関連技術の設定をまとめる」だけで責務を決めない。
59
+ 問い:
60
+
61
+ - 初期構築・接続・日常利用のどこを扱い、読み手は何を済ませてから読み始めるか。
62
+ - 扱わない作業は、どの文書で済ませるか。
63
+
64
+ コツ:
65
+
66
+ - 技術一覧の採用理由や上位設計の目的は写さず、参照に置き換える。
67
+ - 「関連技術の設定をまとめる」のように担当が決まらない書き方になったら、手順 1 の到達状態へ戻る。
70
68
 
71
69
  ### 4.2. 対象環境・前提条件
72
70
 
73
- - 問い: コマンドをどこで、誰が、どの shell・作業ディレクトリで実行するか。OS や版によって変わる条件はあるか。
74
- - 書き方: 実行場所ごとに OS、ランタイム、権限、導入済みの依存、必要資源をそろえる。特別な権限や追加資源が不要なら、その旨を明記する。実測した環境と一般的な推奨環境を分ける。
75
- - 良い例: 「ホストで常駐プロセスを管理し、接続元コンテナで利用確認する。管理者権限を使う操作は導入時だけ」。避けたい例: 「ローカルで実行する」とだけ書き、端末とホストを混同させる。
71
+ 問い:
72
+
73
+ - コマンドを、どこで、誰が、どの shell と作業ディレクトリで実行するか。
74
+ - OS や版によって変わる条件はあるか。
75
+
76
+ コツ:
77
+
78
+ - 「ローカルで」と書きかけたら、端末・ホスト・コンテナのどれかを構築担当者に聞く。
79
+ - 実測した環境と一般的な推奨環境は聞き分けて別の行に書く。
76
80
 
77
81
  ### 4.3. 全体構成・接続経路
78
82
 
79
- - 問い: どのプロセスがどこで動き、どこからどこへ接続するか。待受アドレス、接続先アドレス、公開範囲は対応するか。
80
- - 書き方: 配置と通信方向を図か対応表にし、端末・ホスト・コンテナの境界を先に描く。名前解決、ポート転送、トンネルを使う場合は、経路ごとに入口と出口を結ぶ。
81
- - 良い例: 「接続元 → トンネル → ホストの公開ポート → コンテナの待受ポート」と経路を示す。避けたい例: すべてを同じ `localhost` とし、どの環境のアドレスか説明しない。
83
+ 問い:
84
+
85
+ - どのプロセスがどこで動き、どこからどこへ接続するか。
86
+ - 待受アドレス、接続先アドレス、公開範囲は対応するか。
87
+
88
+ コツ:
89
+
90
+ - 端末・ホスト・コンテナの境界を先に描き、名前解決・ポート転送・トンネルは経路ごとに入口と出口を結ぶ。
91
+ - すべてを `localhost` と書くと、どの環境のアドレスか分からなくなる。
82
92
 
83
93
  ### 4.4. 採用技術・設定
84
94
 
85
- - 問い: その値は何を満たすために採用したか。候補・任意設定・未決事項との違いは何か。設定ファイルと環境変数のどちらが実行プロセスへ反映されるか。
86
- - 書き方: 次の表へ、設定の適用範囲と確認方法まで一行でつなぐ。GUI 設定も画面項目・保存先・反映条件を調べる。推奨値を適用する場合は、採用を決めた記録を別に残す。
87
- - 良い例: 「推奨候補の並列数は評価後に採否を決める。現行の採用値は有効値の確認結果に基づく」。避けたい例: 推奨値を無条件に採用済みの表へ混ぜる。
95
+ 問い:
88
96
 
89
- | 対象・用途 | 設定項目 | 採用値・版 | 適用範囲 | 理由・制約 | 反映・確認方法 |
90
- | ------------------ | -------------- | -------------------- | ------------------------ | -------------- | ------------------------------ |
91
- | 利用場面と構成要素 | 製品上の項目名 | 決定した値・単位・版 | 環境・ユーザー・プロセス | 根拠と適用条件 | 保存先・反映操作・有効値の確認 |
97
+ - その値は何を満たすために採用したか。
98
+ - 設定ファイルと環境変数のどちらが、実行中のプロセスへ届くか。
92
99
 
93
- 下書きでは次のように状態を整理し、未決の値を採用値の代わりに埋めない。
100
+ コツ:
94
101
 
95
- | 状態 | 書き進める方法 |
96
- | ------------ | ---------------------------------------------------------------------- |
97
- | 採用値 | 決定の根拠と対象環境を示し、反映操作と確認へつなぐ |
98
- | 推奨値 | 推奨する条件と採否の判断方法を添え、現行の採用値と分ける |
99
- | 任意の選択肢 | 利用する場合の前提と追加確認を示し、共通手順から分岐させる |
100
- | 確認不足 | _TODO_: 確認対象・方法・担当・確認時期を記す |
101
- | 意思決定待ち | _UNDECIDED_: 選択肢・判断基準・担当・判断期限・未決による影響を記す |
102
- | 仮の前提 | _ASSUMPTION_: 仮置きの根拠・成立条件・検証方法・担当・見直し時期を記す |
102
+ - 値ごとに「実測・決定・公式情報」のどれが根拠かを聞く。根拠が出ない版・容量・並列数は採用値に入れない。
103
+ - 推奨値を採る場合は、採用を決めた記録があるかを確かめる。
104
+ - GUI で設定する項目は、画面項目名と保存先を実際に開いて確かめる。
103
105
 
104
106
  ### 4.5. 導入・初期設定
105
107
 
106
- - 問い: 何を先に導入し、どの保存先を変更するか。既存の利用者設定を残せるか。再起動や権限変更で何が影響を受けるか。
107
- - 書き方: 順序付き手順に実行場所、shell、作業ディレクトリ、事前条件、変更先を付ける。コマンドや再現に必要な補助スクリプトは言語識別子付きコードブロックへ置き、追加・部分変更・全体置換を区別する。導入と起動、起動と再起動は別の段階にする。
108
- - 良い例: 「既存設定の対象セクションへ追加し、他の接続先を保持する。反映前にバックアップを取り、再起動が既存セッションへ与える影響を確認する」。避けたい例: ファイル全体の例を示して、そのまま上書きさせる。
108
+ 問い:
109
+
110
+ - 何を先に導入し、どの保存先を変えるか。
111
+ - 既存の利用者設定を残せるか。再起動で何が影響を受けるか。
112
+
113
+ コツ:
114
+
115
+ - 変更ごとに「追加・部分変更・全体置換」のどれかを決めてから手順を書く。決めずに設定例を置くと、全体の上書きとして読まれやすい。
116
+ - 反映前に取るバックアップと、再起動が既存のセッションへ与える影響を管理者に聞く。
109
117
 
110
118
  ### 4.6. 接続設定と秘密情報の扱い
111
119
 
112
- - 問い: 接続方式と認証方式は何か。接続先の登録名、クライアントの選択名、リクエスト中の識別子は対応するか。例に含める値を公開できるか。
113
- - 書き方: 接続先の基点、認証情報の参照方法、識別子の対応を先に整理する。秘密値を読まずに、設定の仕組みと公開可否を判断し、次の順序で例を作る。
114
- - 良い例: 汎用の接続先 `service.example.invalid` と `<TOKEN>` を説明用に置き、実行時は credential store から渡す方法を示す。避けたい例: 実トークン付き URL や認証設定の全文を貼る。
120
+ 問い:
121
+
122
+ - 接続先の登録名、クライアントの選択名、リクエスト中の識別子は対応するか。
123
+ - 例に含める値を公開できるか。
115
124
 
116
- 1. ポートや接続方式、汎用ホスト名など、再現に必要で公開できる情報を選ぶ。接続情報という理由だけで一律に隠さない。
117
- 2. 個人・組織固有のホスト名、アカウント、URL は公開可否を確かめ、機密なら `<SERVICE_HOST>` などのプレースホルダーへ置き換える。公開可否が不明なら _TODO_ として確認先を示す。
118
- 3. API キー、トークン、パスワード、秘密鍵は実値を載せず、取得・保存・注入・参照方法を書く。認証不要の方式なら、その適用範囲と公開範囲を説明する。
119
- 4. 設定例、URL、出力例、ログ例、コマンド履歴にも秘密が残らない形を選ぶ。公開用の例と実行時に供給する値の対応を説明する。
125
+ コツ:
126
+
127
+ - 秘密値を読まずに、設定の仕組みと公開できるかを管理者に聞く。
128
+ - ポートや汎用ホスト名は、接続情報という理由だけで一律に隠さない。公開できるか不明な固有名は _TODO_ にして確認先を書く。
120
129
 
121
130
  ### 4.7. 動作確認
122
131
 
123
- - 問い: 起動、疎通、認証、識別子の解決、実際の利用のうち何を確認できたか。失敗したら一つ前のどの前提へ戻るか。
124
- - 書き方: 下の段階を対象に合わせて選び、確認対象、実行場所・方法、期待結果、失敗時の確認先を表にする。認証不要などの段階は理由を添えて省く。有効値や版は専用の表示・照会で確かめ、疎通成功だけから設定反映を推定しない。
125
- - 良い例: 「一覧応答は疎通と登録済み識別子の確認に使い、最小入力への応答で利用機能を確かめる」。避けたい例: 「起動したので設定と接続はすべて正常」とする。
132
+ 問い:
133
+
134
+ - 起動、疎通、認証、識別子の解決、実際の利用のうち、何を確かめたか。
135
+ - 失敗したら、一つ前のどの前提へ戻るか。
126
136
 
127
- | 段階 | 確認の組み立て方 | 期待結果と切り分けの例 |
128
- | -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ |
129
- | 基盤・プロセス | 基盤側で依存と起動状態、必要な有効値を確認する | 対象プロセスが稼働し、有効値が採用値に一致する。起動設定・反映操作・ログへ戻る |
130
- | 名前解決・疎通 | 実際の接続元から対象の入口へ到達できるか確認する | 接続でき、所定の応答項目が返る。名前解決・待受・転送・公開範囲を調べる |
131
- | 認証・識別子 | 認証方式と利用対象の登録名・選択名を確認する | 対象の権限と識別子で利用できる。認証の参照先・権限・登録名の対応へ戻る |
132
- | 最小利用 | 小さい入力で一機能を実行し、クライアント経由でも確認する | 意図した結果が得られる。直接利用が成功するならクライアント固有設定を調べる |
137
+ コツ:
133
138
 
134
- 負荷や応答時間の目標を扱うなら、根拠となる要求とともに入力サイズ、並列数、初回・再実行の別、測定方法、合否を判断する時点をそろえる。未実施なら _TODO_ と確認環境・担当・残る方法を残し、想定する期待結果と実測した結果を分ける。
139
+ - 有効値や版は専用の表示・照会で確かめる。疎通の成功から設定の反映は推定できない。
140
+ - 負荷や応答時間を扱うなら、入力サイズ、並列数、初回か再実行か、測定方法、合否を決める時点をそろえて測る。
135
141
 
136
142
  ### 4.8. 継続利用・運用
137
143
 
138
- - 問い: 切断後に戻る場所はどこか。再接続だけで再開するものと、明示的な再開が必要なものは何か。設定、認証状態、作業データ、実行中セッションはどこに保存されるか。
139
- - 書き方: 通信切断、プロセス再起動、環境再構築を分け、保持する状態と復元操作を表にする。長時間実行は監視対象、根拠のある正常範囲、負荷を減らす判断条件を添える。組織的な監視体制やバックアップ方針は運用設計へ委ねる。
140
- - 良い例: 「接続断では実行セッションへ戻り、プロセス終了時は明示的に再開する。再構築時は永続化した設定を復元し、失ったセッションを作り直す」。避けたい例: 「接続し直せばすべて再開する」。
144
+ 問い:
145
+
146
+ - 切断の後にどこへ戻り、再接続だけで再開しないものは何か。
147
+ - 設定、認証状態、作業データ、実行中のセッションはどこに保存されるか。
148
+
149
+ コツ:
150
+
151
+ - 通信切断・プロセス再起動・環境再構築を、一つずつ仮に起こして確かめる。
152
+ - 組織の監視体制やバックアップ方針は書き始めず、運用設計の担当へ渡す。
141
153
 
142
154
  ### 4.9. 制約・トラブルシュート
143
155
 
144
- - 問い: どの症状からどの段階の失敗を疑うか。確認済みの制約と未検証の条件はどれか。
145
- - 書き方: 動作確認の失敗先を症状別に並べ、最初の確認、次の確認、回避・復旧を結ぶ。原因が確定していないものは仮説として扱い、設定の削除や再インストールより先に観測できる情報を選ぶ。
146
- - 良い例: 「基盤からの応答はあるがクライアントで対象を選べない場合、登録識別子と選択名を照合する」。避けたい例: 「接続できなければ再インストール」。
156
+ 問い:
157
+
158
+ - どの症状から、どの段階の失敗を疑うか。
159
+ - 確かめた制約と、まだ確かめていない条件はどれか。
160
+
161
+ コツ:
162
+
163
+ - 設定の削除や再インストールより先に、観測できる情報を確かめる順に並べる。
164
+ - 原因が確定していないものは仮説として書く。
147
165
 
148
166
  ### 4.10. 更新・復旧・撤去
149
167
 
150
- - 問い: 旧方式と共存できるか。何を停止し、何を保存してから変更するか。どの確認で切り戻しを判断するか。
151
- - 書き方: 競合する待受・自動起動・保存先を洗い出し、変更前の退避、旧方式の停止、新方式への変更、確認、切り戻しの順に書く。撤去はプロセス、設定、認証状態、データごとに保持・削除を分ける。
152
- - 良い例: 「新方式の利用確認が失敗したら旧設定へ戻す。データ削除は撤去とは別の選択として影響と復元可否を示す」。避けたい例: 停止や再構築の手順にデータ削除を混ぜる。
168
+ 問い:
169
+
170
+ - 旧方式と共存できるか。何を止め、何を保存してから変えるか。
171
+ - どの確認の結果で切り戻すか。
172
+
173
+ コツ:
174
+
175
+ - 競合する待受、自動起動、保存先を先に洗い出す。
176
+ - データの削除は撤去と別の選択として、影響と復元できるかを聞く。
153
177
 
154
178
  ### 4.11. 参照情報
155
179
 
156
- - 問い: 採用判断や手順のどの主張を、どの資料・確認記録で確かめ直せるか。適用した版や確認日は分かるか。
157
- - 書き方: 公式情報には対象の版や確認日、関連文書にはその責務を添える。設定表や確認項目から根拠へたどれる名前を使い、参考に読んだ資料をすべて採用根拠にしない。
158
- - 良い例: 「環境変数の反映条件」の根拠を、適用した版の公式情報と確認記録へ結ぶ。避けたい例: 製品トップページだけを列挙し、何を裏付けるか示さない。
180
+ 問い:
181
+
182
+ - 採用判断や手順の主張を、どの資料や確認記録で確かめ直せるか。
183
+ - 適用した版や確認日は分かるか。
184
+
185
+ コツ:
186
+
187
+ - 参考に読んだ資料をすべて根拠に並べない。製品のトップページだけでは何を裏付けるか分からない。
159
188
 
160
189
  ## 5. 深掘り手順
161
190
 
162
- 1. 主要な採用設定を一つ選び、利用目的や上位の品質条件へ戻れるか調べる。戻れなければ、値の追加より先に採用理由を明らかにする。
163
- 2. 設定ごとに保存先、適用範囲、優先順位、反映操作、有効値の確認をつなぐ。shell で見える値と常駐プロセスが受け取る値が同じか確かめる。
164
- 3. 接続元を起点に経路をたどり、基盤側で成功する確認とクライアント側で成功する確認を分ける。識別子は登録・選択・確認要求の三か所で照合する。
165
- 4. 再接続や再構築を仮に起こしたとして、保存された設定だけで復帰できるか点検する。セッションや一時データが足りなければ再開操作を具体化する。
166
- 5. 事実に見える未検証の主張を探し、確認不足・意思決定待ち・仮の前提へ分ける。それぞれに確認・判断方法と担当、時期を付ける。
167
- 6. 別冊と同じ設定値を持つ箇所を探し、正本を一つに寄せる。参照側には値の転載に代えて開始条件と本書で変える差分を残す。
191
+ 内容が浅いときは、次の順で対応のない主張を探す。
192
+
193
+ 1. 採用設定の各行が、どの利用目的・品質条件に応えるかを確かめる。戻れない行は、値を足すより先に採用理由を聞く。
194
+ 2. 採用値ごとに、反映する操作と有効値の確認があるかを確かめる。shell で見える値と常駐プロセスが受け取る値は分けて見る。
195
+ 3. 識別子を、登録・選択・確認の要求の三か所で照合し、食い違いを探す。
196
+ 4. 確認済みに見える記述ごとに確認記録があるかを確かめ、なければ _TODO_ か _ASSUMPTION_ に戻す。
197
+ 5. 別冊と同じ設定値を持つ箇所を探し、正本の側へ寄せて、参照側には差分だけを残す。
168
198
 
169
199
  ## 6. 良い例 / 悪い例
170
200
 
171
- | 観点 | 良い例 | 悪い例 |
172
- | ---------------- | ------------------------------------------------------------ | --------------------------------------------------- |
173
- | 文書の分け方 | 基盤導入と接続を分け、接続側に基盤の完了確認と差分だけを書く | 分冊した双方へ同じ導入・設定を転載する |
174
- | 実行場所 | ホストで起動し、接続元コンテナから疎通を確認する | 「端末で実行する」だけで場所を特定しない |
175
- | 値の根拠 | 現行の採用値と推奨候補を分け、未決には判断条件を付ける | 手本の版・容量・並列数をそのまま必須にする |
176
- | 設定の反映 | 保存先と優先順位を示し、反映後に対象プロセスの有効値を調べる | shell の値や API の応答だけで全設定の反映を断定する |
177
- | 既存設定との統合 | 既存の接続先を保持して対象項目を追加する | 設定例で既存ファイル全体を無条件に置換する |
178
- | 確認の段階 | 疎通、認証、識別子、最小利用を分け、失敗時に戻る箇所を示す | クライアントを起動できれば利用可能とする |
179
- | 継続利用 | 切断後の再接続と処理の再開を区別する | 履歴が保存されれば進行中の処理も自動再開するとする |
180
- | 秘密情報 | 公開可能な経路を示し、秘密値は保存・参照方法で説明する | 認証設定やログの全文を実値のまま貼る |
181
- | 撤去 | 自動起動・本体・設定・データの扱いと復元可否を分ける | アンインストールに全データ削除を含める |
201
+ | 観点 | 良い例 | 悪い例 |
202
+ | ---------------- | -------------------------------------------------------------- | --------------------------------------------------- |
203
+ | 文書の分け方 | 基盤導入と接続を分け、接続側に基盤の完了確認と差分だけを書く | 分冊した双方へ同じ導入・設定を転載する |
204
+ | 実行場所 | ホストで起動し、接続元コンテナから疎通を確認する | 「端末で実行する」だけで場所を特定しない |
205
+ | 値の根拠 | 現行の採用値と推奨候補を分け、未決には判断条件を付ける | 手本の版・容量・並列数をそのまま必須にする |
206
+ | 設定の反映 | 保存先と優先順位を示し、反映後に対象プロセスの有効値を調べる | shell の値や API の応答だけで全設定の反映を断定する |
207
+ | 既存設定との統合 | 既存の接続先を保持して対象項目を追加する | 設定例で既存ファイル全体を無条件に置換する |
208
+ | 継続利用 | 切断後の再接続と処理の再開を区別する | 履歴が保存されれば進行中の処理も自動再開するとする |
209
+ | 秘密情報 | `<TOKEN>` を置き、実行時に credential store から渡す方法を示す | 実トークン付きの URL や認証設定の全文を貼る |
182
210
 
183
211
  ## 7. レビュー観点
184
212
 
185
- | 観点 | 確認内容 |
186
- | ------------ | ---------------------------------------------------------------------------------------- |
187
- | 目的との対応 | 主要な設定が利用目的・品質条件に結び付き、採用理由と制約を説明できるか |
188
- | 文書の境界 | 一冊の開始・完了状態が分かり、分冊した設定の正本と差分をたどれるか |
189
- | 環境と再現性 | OS・版・権限・依存・資源、実行場所・shell・変更先を特定できるか |
190
- | 判断の確度 | 採用・推奨・任意・未決・仮説が混ざらず、未確定事項の担当と確認・判断時期が分かるか |
191
- | 反映と検証 | 採用値から反映操作・有効値・最終利用までを確認でき、失敗時の戻り先が分かるか |
192
- | 継続性と復旧 | 切断・再起動・再構築で保持・喪失する状態と、再開・切り戻し操作が対応するか |
193
- | 公開適性 | 接続経路の説明を残しつつ、秘密値や機密の固有情報を本文・設定例・出力例から除けているか |
194
- | 委譲と追跡 | 詳細 API・内部設計・組織的な運用方針を担当文書へ委ね、採用判断と確認の根拠を追跡できるか |
213
+ | 観点 | 確認内容 |
214
+ | ------------ | ---------------------------------------------------------------------------- |
215
+ | 文書の境界 | 一冊の開始状態と到達状態が分かり、分冊した設定の正本と差分をたどれるか |
216
+ | 再現性 | 別の担当者が、実行場所・shell・変更先を特定して同じ手順を進められるか |
217
+ | 判断の確度 | 採用値・推奨候補・任意の選択肢・未決・仮説が混ざっていないか |
218
+ | 継続性と復旧 | 切断・再起動・再構築で保持・喪失する状態と、再開・切り戻しの操作が対応するか |
219
+ | 委譲の境界 | 内部設計・詳細 API・組織の運用方針を書きすぎていないか |
195
220
 
196
221
  ## 8. 仕上げチェック
197
222
 
198
- - 初期構築・接続設定・日常利用の担当範囲と対象外が分かり、別冊の手順を始める条件が具体化されている。
199
- - 構成の呼び名と各操作の実行場所が一致し、接続元から利用先までの経路と公開範囲をたどれる。
200
- - 採用値に根拠と適用範囲があり、推奨値や任意設定、未決事項を採用済みと誤読しない。
201
- - 設定の保存先、優先順位、反映条件がつながり、既存設定を保持する方法と変更影響が分かる。
202
- - 確認に期待結果と失敗時の確認先があり、疎通と設定反映、最小利用を別々に判定できる。未実施の確認を成功としていない。
203
- - 継続利用や変更を扱う箇所には、状態の保存、再開、切り戻し、削除の影響が対応している。
204
- - 秘密値を含めず、機密情報のプレースホルダーと実行時の取得・参照方法が対応している。
205
- - 参照先の存在、表内の wikilink の区切りのエスケープ、見出し名による章参照を確かめた。未作成の文書はコード表記で仮置きしている。
206
- - 確認不足・未決・仮の前提には担当と確認・判断の時期があり、判断や再現を妨げる点を読み手が識別できる。
223
+ - 採用設定の各行が利用目的に対応し、反映する操作と確認結果までたどれる。
224
+ - 構成の呼び名と、各操作の実行場所が一致している。
225
+ - 確認記録のない確認を、成功と書いていない。
226
+ - 本文・設定例・出力例・ログ例に秘密値がない。