specdojo 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +22 -0
- package/README.md +82 -38
- package/dist/agent-response.js +27 -0
- package/dist/agent.js +124 -0
- package/dist/build-command.js +149 -0
- package/dist/build-if-stale.js +35 -0
- package/dist/catalog-build.js +1079 -0
- package/dist/catalog-generate.js +226 -0
- package/dist/catalog-paths.js +31 -0
- package/dist/catalog-plan-generate.js +301 -0
- package/dist/catalog-plan-prompt.js +73 -0
- package/dist/catalog-plan.js +471 -0
- package/dist/catalog-scaffold.js +255 -0
- package/dist/catalog-types.js +4 -0
- package/dist/catalog.js +606 -0
- package/dist/dashboard.js +980 -0
- package/dist/deliverable-trash.js +148 -0
- package/dist/deliverable.js +97 -0
- package/dist/dist-freshness.js +150 -0
- package/dist/doc-index.js +424 -0
- package/dist/exec-agent-config.js +172 -0
- package/dist/exec-agent-git-state.js +136 -0
- package/dist/exec-agent-protected-config.js +276 -0
- package/dist/exec-events.js +250 -112
- package/dist/exec-evidence.js +317 -0
- package/dist/exec-format.js +45 -0
- package/dist/exec-limit.js +202 -0
- package/dist/exec-parent-validation.js +169 -0
- package/dist/exec-pipeline-state.js +160 -0
- package/dist/exec-plans.js +1016 -0
- package/dist/exec-project.js +25 -11
- package/dist/exec-protection-handoff.js +169 -0
- package/dist/exec-provider-scaffold.js +99 -0
- package/dist/exec-register-resume.js +196 -0
- package/dist/exec-register.js +281 -0
- package/dist/exec-reporter.js +329 -0
- package/dist/exec-results.js +510 -0
- package/dist/exec-run-lock.js +149 -0
- package/dist/exec-run.js +4953 -0
- package/dist/exec-schedule-calendar.js +86 -9
- package/dist/exec-schedule-cpm.js +30 -12
- package/dist/exec-schedule-gantt-chart-render.js +428 -0
- package/dist/exec-schedule-gantt-chart-scope.js +111 -0
- package/dist/exec-schedule-gantt-chart.js +2 -0
- package/dist/exec-schedule-hash.js +34 -25
- package/dist/exec-schedule-index.js +200 -67
- package/dist/exec-schedule-initial.js +100 -0
- package/dist/exec-schedule-progress.js +51 -26
- package/dist/exec-schedule-ready.js +71 -27
- package/dist/exec-schedule.js +171 -93
- package/dist/exec-shared.js +146 -25
- package/dist/exec-strategy.js +547 -0
- package/dist/exec-task-view.js +64 -0
- package/dist/exec-trial.js +895 -0
- package/dist/exec-worktree-command.js +426 -0
- package/dist/exec-worktree-ops.js +847 -0
- package/dist/exec-worktree.js +359 -0
- package/dist/exec.js +744 -192
- package/dist/frontmatter-namespace.js +48 -0
- package/dist/git-environment.js +23 -0
- package/dist/grade-result.js +137 -0
- package/dist/grade.js +2456 -0
- package/dist/index-command.js +103 -0
- package/dist/job.js +1081 -0
- package/dist/kata-command.js +303 -0
- package/dist/kata.js +187 -0
- package/dist/package-paths.js +15 -0
- package/dist/practice-id.js +24 -0
- package/dist/register-date.js +122 -0
- package/dist/register-events.js +363 -0
- package/dist/register-history.js +323 -0
- package/dist/register-item.js +455 -0
- package/dist/register-migrate-timestamps.js +176 -0
- package/dist/register.js +2199 -0
- package/dist/review-plan.js +199 -0
- package/dist/review-types.js +1 -0
- package/dist/role-types.js +1 -0
- package/dist/routine.js +814 -0
- package/dist/schedule-approach.js +252 -0
- package/dist/schedule-build.js +552 -0
- package/dist/schedule-phase-sets.js +73 -0
- package/dist/schedule-strategy-generate.js +812 -0
- package/dist/schedule-strategy-profiles.js +276 -0
- package/dist/schedule.js +420 -0
- package/dist/spawn-self.js +28 -0
- package/dist/specdojo-config.js +133 -39
- package/dist/specdojo.js +55 -7
- package/dist/template-frontmatter.js +89 -0
- package/dist/template-resolution.js +92 -0
- package/dist/timeline-build.js +334 -0
- package/dist/timeline.js +107 -0
- package/dist/watch.js +313 -0
- package/dist/yaml-pages-command.js +28 -0
- package/dist/yaml-pages.js +180 -0
- package/dist/yaml-schema-modeline.js +49 -0
- package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +600 -0
- package/docs/ja/specdojo/exec-templates/xep-bootstrap-template.md +120 -0
- package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +37 -0
- package/docs/ja/specdojo/exec-templates/xep-cross-deliverable-dedup-template.md +51 -0
- package/docs/ja/specdojo/exec-templates/xep-freeform-template.md +74 -0
- package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +109 -0
- package/docs/ja/specdojo/exec-templates/xep-job-template.md +43 -0
- package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +82 -0
- package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +86 -0
- package/docs/ja/specdojo/exec-templates/xep-register-investigate-template.md +42 -0
- package/docs/ja/specdojo/exec-templates/xep-register-template.md +49 -0
- package/docs/ja/specdojo/exec-templates/xep-retrofit-template.md +98 -0
- package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +86 -0
- package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +86 -0
- package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +86 -0
- package/docs/ja/specdojo/exec-templates/xep-template.md +66 -0
- package/docs/ja/specdojo/exec-templates/xer-cross-deliverable-dedup-template.md +31 -0
- package/docs/ja/specdojo/exec-templates/xer-human-bootstrap-finalize-template.md +40 -0
- package/docs/ja/specdojo/exec-templates/xer-human-finalize-template.md +30 -0
- package/docs/ja/specdojo/exec-templates/xer-template.md +19 -0
- package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +70 -0
- package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +97 -0
- package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +76 -0
- package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +73 -0
- package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +74 -0
- package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +74 -0
- package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +73 -0
- package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +73 -0
- package/docs/ja/specdojo/exec-templates/xrp-template.md +67 -0
- package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +7 -0
- package/docs/ja/specdojo/exec-templates/xrr-template.md +21 -0
- package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +7 -0
- package/docs/ja/specdojo/guides/branch-workflow-guide.md +354 -0
- package/docs/ja/specdojo/guides/docs-editing-guide.md +327 -0
- package/docs/ja/specdojo/guides/docs-structure-guide.md +519 -0
- package/docs/ja/specdojo/guides/exec-config-guide.md +589 -0
- package/docs/ja/specdojo/guides/exec-operation-guide.md +440 -0
- package/docs/ja/specdojo/guides/exec-worktree-guide.md +318 -0
- package/docs/ja/specdojo/guides/kata-guide.md +89 -0
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +127 -0
- package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +228 -0
- package/docs/ja/specdojo/guides/practice-system-composition-guide.md +111 -0
- package/docs/ja/specdojo/guides/quick-start-guide.md +473 -0
- package/docs/ja/specdojo/guides/register-operation-guide.md +418 -0
- package/docs/ja/specdojo/guides/review-guide.md +428 -0
- package/docs/ja/specdojo/guides/routine-operation-guide.md +282 -0
- package/docs/ja/specdojo/guides/ryu-guide.md +230 -0
- package/docs/ja/specdojo/guides/schedule-design-guide.md +429 -0
- package/docs/ja/specdojo/guides/schedule-operation-guide.md +151 -0
- package/docs/ja/specdojo/guides/specdojo-overview-guide.md +257 -0
- package/docs/ja/specdojo/guides/timeline-design-guide.md +160 -0
- package/docs/ja/specdojo/guides/track-design-guide.md +215 -0
- package/docs/ja/specdojo/guides/use-case-guide.md +133 -0
- package/docs/ja/specdojo/guides/waza-guide.md +224 -0
- package/docs/ja/specdojo/index.md +33 -0
- package/docs/ja/specdojo/philosophy/needs-to-implementation-philosophy.md +212 -0
- package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +242 -0
- package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +198 -0
- package/docs/ja/specdojo/recipes/cdfd-recipe.md +218 -0
- package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +198 -0
- package/docs/ja/specdojo/recipes/exec-human-finalize-recipe.md +100 -0
- package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +148 -0
- package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +97 -0
- package/docs/ja/specdojo/recipes/pm-members-recipe.md +149 -0
- package/docs/ja/specdojo/recipes/pm-organization-recipe.md +96 -0
- package/docs/ja/specdojo/recipes/pm-plan-recipe.md +98 -0
- package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +97 -0
- package/docs/ja/specdojo/recipes/pm-raci-recipe.md +96 -0
- package/docs/ja/specdojo/recipes/pm-roles-recipe.md +136 -0
- package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +162 -0
- package/docs/ja/specdojo/recipes/prj-charter-recipe.md +187 -0
- package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +235 -0
- package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +205 -0
- package/docs/ja/specdojo/recipes/prj-overview-recipe.md +289 -0
- package/docs/ja/specdojo/recipes/prj-scope-recipe.md +201 -0
- package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +168 -0
- package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +179 -0
- package/docs/ja/specdojo/recipes/stsd-recipe.md +138 -0
- package/docs/ja/specdojo/references/command-reference.md +718 -0
- package/docs/ja/specdojo/references/deliverables-reference.md +407 -0
- package/docs/ja/specdojo/references/directory-layout-reference.md +280 -0
- package/docs/ja/specdojo/references/specdojo-config-reference.md +133 -0
- package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +372 -0
- package/docs/ja/specdojo/rulebooks/atc-rulebook.md +302 -0
- package/docs/ja/specdojo/rulebooks/bac-rulebook.md +331 -0
- package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +134 -0
- package/docs/ja/specdojo/rulebooks/bds-rulebook.md +207 -0
- package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +102 -0
- package/docs/ja/specdojo/rulebooks/bes-rulebook.md +131 -0
- package/docs/ja/specdojo/rulebooks/bps-rulebook.md +269 -0
- package/docs/ja/specdojo/rulebooks/br-rulebook.md +187 -0
- package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +279 -0
- package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +219 -0
- package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +233 -0
- package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +182 -0
- package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +171 -0
- package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +105 -0
- package/docs/ja/specdojo/rulebooks/cld-rulebook.md +195 -0
- package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +285 -0
- package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +292 -0
- package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +171 -0
- package/docs/ja/specdojo/rulebooks/cop-rulebook.md +325 -0
- package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +266 -0
- package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +294 -0
- package/docs/ja/specdojo/rulebooks/cstd-rulebook.md +21 -0
- package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +401 -0
- package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +311 -0
- package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +158 -0
- package/docs/ja/specdojo/rulebooks/dct-rulebook.md +287 -0
- package/docs/ja/specdojo/rulebooks/dec-rulebook.md +62 -0
- package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +100 -0
- package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +298 -0
- package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +379 -0
- package/docs/ja/specdojo/rulebooks/etc-rulebook.md +310 -0
- package/docs/ja/specdojo/rulebooks/gl-rulebook.md +86 -0
- package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +297 -0
- package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +79 -0
- package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +213 -0
- package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +311 -0
- package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +94 -0
- package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +81 -0
- package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +117 -0
- package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +118 -0
- package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +116 -0
- package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +116 -0
- package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +116 -0
- package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +421 -0
- package/docs/ja/specdojo/rulebooks/itc-rulebook.md +307 -0
- package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +312 -0
- package/docs/ja/specdojo/rulebooks/mm-rulebook.md +63 -0
- package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +353 -0
- package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +184 -0
- package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +179 -0
- package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +184 -0
- package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +183 -0
- package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +185 -0
- package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +185 -0
- package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +186 -0
- package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +186 -0
- package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +184 -0
- package/docs/ja/specdojo/rulebooks/ntp-rulebook.md +61 -0
- package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +84 -0
- package/docs/ja/specdojo/rulebooks/opd-rulebook.md +357 -0
- package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +80 -0
- package/docs/ja/specdojo/rulebooks/opr-rulebook.md +484 -0
- package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +120 -0
- package/docs/ja/specdojo/rulebooks/otp-rulebook.md +293 -0
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +211 -0
- package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +94 -0
- package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +116 -0
- package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +93 -0
- package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +190 -0
- package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +108 -0
- package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +122 -0
- package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +117 -0
- package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +116 -0
- package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +93 -0
- package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +146 -0
- package/docs/ja/specdojo/rulebooks/pr-rulebook.md +65 -0
- package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +178 -0
- package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +232 -0
- package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +235 -0
- package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +242 -0
- package/docs/ja/specdojo/rulebooks/prj-overview-rulebook.md +187 -0
- package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +201 -0
- package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +165 -0
- package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +165 -0
- package/docs/ja/specdojo/rulebooks/sac-rulebook.md +202 -0
- package/docs/ja/specdojo/rulebooks/sch-rulebook.md +139 -0
- package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +63 -0
- package/docs/ja/specdojo/rulebooks/sf-rulebook.md +93 -0
- package/docs/ja/specdojo/rulebooks/sld-rulebook.md +93 -0
- package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +329 -0
- package/docs/ja/specdojo/rulebooks/stc-rulebook.md +297 -0
- package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +132 -0
- package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +215 -0
- package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +376 -0
- package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +313 -0
- package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +246 -0
- package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +119 -0
- package/docs/ja/specdojo/rulebooks/tml-rulebook.md +188 -0
- package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +114 -0
- package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +117 -0
- package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +101 -0
- package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +103 -0
- package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +396 -0
- package/docs/ja/specdojo/rulebooks/uis-rulebook.md +207 -0
- package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +387 -0
- package/docs/ja/specdojo/rulebooks/utc-rulebook.md +303 -0
- package/docs/ja/specdojo/samples/atc-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/atc-sample.md +41 -0
- package/docs/ja/specdojo/samples/bac-sample.md +38 -0
- package/docs/ja/specdojo/samples/bdd-sample.yaml +71 -0
- package/docs/ja/specdojo/samples/bds-sample.md +38 -0
- package/docs/ja/specdojo/samples/bes-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/bes-sample.md +38 -0
- package/docs/ja/specdojo/samples/bps-sample.md +38 -0
- package/docs/ja/specdojo/samples/br-sample.md +40 -0
- package/docs/ja/specdojo/samples/ccd-sample.md +38 -0
- package/docs/ja/specdojo/samples/cdfd-overview-sample.md +284 -0
- package/docs/ja/specdojo/samples/cdfd-sample.md +229 -0
- package/docs/ja/specdojo/samples/cdfd-uc-sample.md +146 -0
- package/docs/ja/specdojo/samples/cdsd-sample.md +38 -0
- package/docs/ja/specdojo/samples/cld-sample.md +38 -0
- package/docs/ja/specdojo/samples/cnd-sample.md +38 -0
- package/docs/ja/specdojo/samples/cop-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/cop-sample.md +38 -0
- package/docs/ja/specdojo/samples/cpd-sample.md +38 -0
- package/docs/ja/specdojo/samples/cstd-sample.md +11 -0
- package/docs/ja/specdojo/samples/cxd-sample.md +38 -0
- package/docs/ja/specdojo/samples/dct-index-sample.yaml +39 -0
- package/docs/ja/specdojo/samples/dct-sample.yaml +91 -0
- package/docs/ja/specdojo/samples/dec-sample.md +39 -0
- package/docs/ja/specdojo/samples/dmd-index-sample.md +50 -0
- package/docs/ja/specdojo/samples/dmd-sample.md +74 -0
- package/docs/ja/specdojo/samples/etc-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/etc-sample.md +38 -0
- package/docs/ja/specdojo/samples/gl-sample.yaml +37 -0
- package/docs/ja/specdojo/samples/ifd-sample.md +38 -0
- package/docs/ja/specdojo/samples/ifx-api-sample.yaml +102 -0
- package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +107 -0
- package/docs/ja/specdojo/samples/ifx-file-sample.md +38 -0
- package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +89 -0
- package/docs/ja/specdojo/samples/imp-business-sample.md +66 -0
- package/docs/ja/specdojo/samples/imp-data-sample.md +60 -0
- package/docs/ja/specdojo/samples/imp-interface-sample.md +60 -0
- package/docs/ja/specdojo/samples/imp-operations-sample.md +60 -0
- package/docs/ja/specdojo/samples/imp-test-sample.md +60 -0
- package/docs/ja/specdojo/samples/itc-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/itc-sample.md +38 -0
- package/docs/ja/specdojo/samples/mip-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/mm-sample.md +35 -0
- package/docs/ja/specdojo/samples/mtp-sample.md +38 -0
- package/docs/ja/specdojo/samples/nfr-availability-sample.md +38 -0
- package/docs/ja/specdojo/samples/nfr-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/nfr-integrity-sample.md +38 -0
- package/docs/ja/specdojo/samples/nfr-maintainability-sample.md +38 -0
- package/docs/ja/specdojo/samples/nfr-operations-sample.md +38 -0
- package/docs/ja/specdojo/samples/nfr-performance-sample.md +38 -0
- package/docs/ja/specdojo/samples/nfr-reliability-sample.md +38 -0
- package/docs/ja/specdojo/samples/nfr-security-safety-sample.md +38 -0
- package/docs/ja/specdojo/samples/nfr-usability-sample.md +38 -0
- package/docs/ja/specdojo/samples/ntp-sample.md +38 -0
- package/docs/ja/specdojo/samples/opd-access-control-sample.md +29 -0
- package/docs/ja/specdojo/samples/opd-incident-management-sample.md +31 -0
- package/docs/ja/specdojo/samples/opd-index-sample.md +41 -0
- package/docs/ja/specdojo/samples/opd-monitoring-sample.md +32 -0
- package/docs/ja/specdojo/samples/opd-sample.md +38 -0
- package/docs/ja/specdojo/samples/opr-access-control-sample.md +24 -0
- package/docs/ja/specdojo/samples/opr-backup-restore-sample.md +27 -0
- package/docs/ja/specdojo/samples/opr-batch-sample.md +23 -0
- package/docs/ja/specdojo/samples/opr-change-sample.md +24 -0
- package/docs/ja/specdojo/samples/opr-incident-sample.md +38 -0
- package/docs/ja/specdojo/samples/opr-index-sample.md +43 -0
- package/docs/ja/specdojo/samples/opr-monitoring-sample.md +27 -0
- package/docs/ja/specdojo/samples/opr-sample.md +38 -0
- package/docs/ja/specdojo/samples/opr-support-sample.md +23 -0
- package/docs/ja/specdojo/samples/otp-index-sample.md +66 -0
- package/docs/ja/specdojo/samples/otp-sample.md +68 -0
- package/docs/ja/specdojo/samples/pm-change-request-log-sample.md +47 -0
- package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +46 -0
- package/docs/ja/specdojo/samples/pm-issue-log-sample.md +45 -0
- package/docs/ja/specdojo/samples/pm-members-sample.yaml +103 -0
- package/docs/ja/specdojo/samples/pm-organization-sample.md +46 -0
- package/docs/ja/specdojo/samples/pm-plan-sample.md +57 -0
- package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +52 -0
- package/docs/ja/specdojo/samples/pm-raci-sample.md +57 -0
- package/docs/ja/specdojo/samples/pm-risk-register-sample.md +43 -0
- package/docs/ja/specdojo/samples/pm-roles-sample.yaml +41 -0
- package/docs/ja/specdojo/samples/pr-sample.md +39 -0
- package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +57 -0
- package/docs/ja/specdojo/samples/prj-charter-sample.md +121 -0
- package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +105 -0
- package/docs/ja/specdojo/samples/prj-issues-and-approach-sample.md +78 -0
- package/docs/ja/specdojo/samples/prj-overview-sample.md +95 -0
- package/docs/ja/specdojo/samples/prj-scope-sample.md +71 -0
- package/docs/ja/specdojo/samples/prj-stakeholder-register-sample.md +60 -0
- package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +62 -0
- package/docs/ja/specdojo/samples/sac-sample.md +38 -0
- package/docs/ja/specdojo/samples/sf-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/sf-sample.md +38 -0
- package/docs/ja/specdojo/samples/sld-sample.md +38 -0
- package/docs/ja/specdojo/samples/stc-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/stc-sample.md +38 -0
- package/docs/ja/specdojo/samples/stsd-sample.md +58 -0
- package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +38 -0
- package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +38 -0
- package/docs/ja/specdojo/samples/sysd-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/trc-requirements-to-specs-sample.md +56 -0
- package/docs/ja/specdojo/samples/trc-requirements-to-tests-sample.md +56 -0
- package/docs/ja/specdojo/samples/tsd-index-sample.md +29 -0
- package/docs/ja/specdojo/samples/tsd-sample.md +38 -0
- package/docs/ja/specdojo/samples/tsp-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/uis-sample.md +38 -0
- package/docs/ja/specdojo/samples/utc-index-sample.md +38 -0
- package/docs/ja/specdojo/samples/utc-sample.md +38 -0
- package/docs/ja/specdojo/schemas/v1/guide-content.schema.yaml +20 -0
- package/docs/ja/specdojo/schemas/v1/philosophy-content.schema.yaml +21 -0
- package/docs/ja/specdojo/schemas/v1/reference-content.schema.yaml +21 -0
- package/docs/ja/specdojo/standards/document-metadata-standard.md +323 -0
- package/docs/ja/specdojo/standards/exec-human-finalize-standard.md +75 -0
- package/docs/ja/specdojo/standards/git-branching-standard.md +227 -0
- package/docs/ja/specdojo/standards/guide-authoring-standard.md +124 -0
- package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +929 -0
- package/docs/ja/specdojo/standards/job-definition-standard.md +148 -0
- package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +431 -0
- package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +113 -0
- package/docs/ja/specdojo/standards/recipe-authoring-standard.md +143 -0
- package/docs/ja/specdojo/standards/reference-authoring-standard.md +99 -0
- package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +140 -0
- package/docs/ja/specdojo/standards/sample-authoring-standard.md +151 -0
- package/docs/ja/specdojo/standards/standard-authoring-standard.md +108 -0
- package/docs/ja/specdojo/standards/template-authoring-standard.md +101 -0
- package/docs/ja/specdojo/standards/test-document-scope-standard.md +176 -0
- package/docs/ja/specdojo/templates/cdfd-overview-template.md +199 -0
- package/docs/ja/specdojo/templates/cdfd-template.md +173 -0
- package/docs/ja/specdojo/templates/cdfd-uc-template.md +148 -0
- package/docs/ja/specdojo/templates/dct-architecture-template.yaml +136 -0
- package/docs/ja/specdojo/templates/dct-business-acceptance-criteria-template.yaml +34 -0
- package/docs/ja/specdojo/templates/dct-business-model-bes-template.yaml +75 -0
- package/docs/ja/specdojo/templates/dct-business-model-bps-template.yaml +49 -0
- package/docs/ja/specdojo/templates/dct-business-model-br-template.yaml +50 -0
- package/docs/ja/specdojo/templates/dct-data-flow-template.yaml +40 -0
- package/docs/ja/specdojo/templates/dct-data-model-bdd-template.yaml +46 -0
- package/docs/ja/specdojo/templates/dct-data-model-ccd-template.yaml +46 -0
- package/docs/ja/specdojo/templates/dct-data-model-cdsd-template.yaml +41 -0
- package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +38 -0
- package/docs/ja/specdojo/templates/dct-data-model-sld-template.yaml +38 -0
- package/docs/ja/specdojo/templates/dct-data-model-stsd-template.yaml +46 -0
- package/docs/ja/specdojo/templates/dct-external-interface-specs-template.yaml +114 -0
- package/docs/ja/specdojo/templates/dct-glossary-template.yaml +35 -0
- package/docs/ja/specdojo/templates/dct-impact-analysis-template.yaml +138 -0
- package/docs/ja/specdojo/templates/dct-index-template.md +40 -0
- package/docs/ja/specdojo/templates/dct-migration-planning-template.yaml +148 -0
- package/docs/ja/specdojo/templates/dct-non-functional-requirements-template.yaml +222 -0
- package/docs/ja/specdojo/templates/dct-operations-template.yaml +108 -0
- package/docs/ja/specdojo/templates/dct-project-definition-template.yaml +210 -0
- package/docs/ja/specdojo/templates/dct-project-management-template.yaml +423 -0
- package/docs/ja/specdojo/templates/dct-system-acceptance-criteria-template.yaml +37 -0
- package/docs/ja/specdojo/templates/dct-system-design-template.yaml +82 -0
- package/docs/ja/specdojo/templates/dct-system-functions-template.yaml +58 -0
- package/docs/ja/specdojo/templates/dct-test-specs-template.yaml +261 -0
- package/docs/ja/specdojo/templates/dct-user-interface-model-template.yaml +60 -0
- package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +88 -0
- package/docs/ja/specdojo/templates/opr-template.md +85 -0
- package/docs/ja/specdojo/templates/pjr-change-request-template.md +60 -0
- package/docs/ja/specdojo/templates/pjr-decision-template.md +61 -0
- package/docs/ja/specdojo/templates/pjr-index-template.md +49 -0
- package/docs/ja/specdojo/templates/pjr-issue-template.md +50 -0
- package/docs/ja/specdojo/templates/pjr-note-template.md +35 -0
- package/docs/ja/specdojo/templates/pjr-question-template.md +53 -0
- package/docs/ja/specdojo/templates/pjr-risk-template.md +49 -0
- package/docs/ja/specdojo/templates/pjr-todo-template.md +41 -0
- package/docs/ja/specdojo/templates/pjr-views-by-owner-template.md +22 -0
- package/docs/ja/specdojo/templates/pjr-views-by-priority-template.md +22 -0
- package/docs/ja/specdojo/templates/pjr-views-by-status-template.md +22 -0
- package/docs/ja/specdojo/templates/pm-change-request-log-template.md +20 -0
- package/docs/ja/specdojo/templates/pm-communication-plan-template.md +46 -0
- package/docs/ja/specdojo/templates/pm-decision-log-template.md +20 -0
- package/docs/ja/specdojo/templates/pm-issue-log-template.md +20 -0
- package/docs/ja/specdojo/templates/pm-members-template.yaml +105 -0
- package/docs/ja/specdojo/templates/pm-organization-template.md +44 -0
- package/docs/ja/specdojo/templates/pm-plan-template.md +52 -0
- package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +46 -0
- package/docs/ja/specdojo/templates/pm-raci-template.md +51 -0
- package/docs/ja/specdojo/templates/pm-risk-register-template.md +20 -0
- package/docs/ja/specdojo/templates/pm-roles-template.yaml +53 -0
- package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +59 -0
- package/docs/ja/specdojo/templates/prj-charter-template.md +116 -0
- package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +116 -0
- package/docs/ja/specdojo/templates/prj-issues-and-approach-template.md +89 -0
- package/docs/ja/specdojo/templates/prj-overview-template.md +85 -0
- package/docs/ja/specdojo/templates/prj-scope-template.md +75 -0
- package/docs/ja/specdojo/templates/prj-stakeholder-register-template.md +64 -0
- package/docs/ja/specdojo/templates/prj-success-criteria-and-acceptance-criteria-template.md +60 -0
- package/docs/ja/specdojo/templates/stsd-template.md +57 -0
- package/docs/specdojo/schemas/v1/bdd.schema.yaml +230 -0
- package/docs/specdojo/schemas/v1/common-frontmatter.schema.yaml +77 -0
- package/docs/specdojo/schemas/v1/dct-index.schema.yaml +85 -0
- package/docs/specdojo/schemas/v1/dct-plan.schema.yaml +324 -0
- package/docs/specdojo/schemas/v1/dct.schema.yaml +368 -0
- package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +91 -0
- package/docs/specdojo/schemas/v1/esil.schema.yaml +142 -0
- package/docs/specdojo/schemas/v1/exec-common.schema.yaml +101 -0
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +272 -0
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +162 -0
- package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +126 -0
- package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +151 -0
- package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +144 -0
- package/docs/specdojo/schemas/v1/grade-done-criteria.schema.yaml +79 -0
- package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +60 -0
- package/docs/specdojo/schemas/v1/grade-result.schema.yaml +118 -0
- package/docs/specdojo/schemas/v1/guide-frontmatter.schema.yaml +19 -0
- package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +293 -0
- package/docs/specdojo/schemas/v1/job-run.schema.yaml +90 -0
- package/docs/specdojo/schemas/v1/job.schema.yaml +198 -0
- package/docs/specdojo/schemas/v1/philosophy-frontmatter.schema.yaml +19 -0
- package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +56 -0
- package/docs/specdojo/schemas/v1/pm-members.schema.yaml +252 -0
- package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +387 -0
- package/docs/specdojo/schemas/v1/pm-roles.schema.yaml +106 -0
- package/docs/specdojo/schemas/v1/recipe-frontmatter.schema.yaml +27 -0
- package/docs/specdojo/schemas/v1/reference-frontmatter.schema.yaml +18 -0
- package/docs/specdojo/schemas/v1/register-events.schema.yaml +106 -0
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +204 -0
- package/docs/specdojo/schemas/v1/routine-run.schema.yaml +36 -0
- package/docs/specdojo/schemas/v1/routine.schema.yaml +87 -0
- package/docs/specdojo/schemas/v1/rulebook-frontmatter.schema.yaml +61 -0
- package/docs/specdojo/schemas/v1/sch-common.schema.yaml +258 -0
- package/docs/specdojo/schemas/v1/sch-defaults.schema.yaml +48 -0
- package/docs/specdojo/schemas/v1/sch-milestones.schema.yaml +64 -0
- package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +772 -0
- package/docs/specdojo/schemas/v1/sch-track.schema.yaml +66 -0
- package/docs/specdojo/schemas/v1/standard-frontmatter.schema.yaml +18 -0
- package/docs/specdojo/schemas/v1/tml-index.schema.yaml +103 -0
- package/package.json +120 -24
- package/templates/claude/README.md +46 -0
- package/templates/claude/agents/claude-expert-review-executor.md +14 -0
- package/templates/claude/agents/claude-review-executor.md +14 -0
- package/templates/claude/settings.edit.json +6 -0
- package/templates/claude/settings.report.json +6 -0
- package/templates/claude/settings.review.json +7 -0
- package/templates/codex/README.md +61 -0
- package/templates/codex/agents/codex-executor.toml +12 -0
- package/templates/codex/agents/codex-expert-executor.toml +12 -0
- package/templates/codex/agents/codex-expert-review-executor.toml +10 -0
- package/templates/codex/agents/codex-review-executor.toml +10 -0
- package/templates/copilot/README.md +41 -0
- package/templates/copilot/exec-defaults-snippet.yaml +28 -0
- package/templates/copilot/pm-members-snippet.yaml +44 -0
- package/templates/opencode/README.md +41 -0
- package/templates/opencode/agents/opencode-executor.md +59 -0
- package/templates/opencode/agents/opencode-reporter.md +26 -0
- package/templates/opencode/agents/opencode-review-executor.md +48 -0
- package/dist/exec-schedule-timeline-render.js +0 -201
- package/dist/exec-schedule-timeline.js +0 -2
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
---
|
|
2
|
+
specdojo:
|
|
3
|
+
id: specdojo:needs-to-implementation-philosophy
|
|
4
|
+
type: philosophy
|
|
5
|
+
status: draft
|
|
6
|
+
supersedes:
|
|
7
|
+
- concept-system-philosophy
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# 要求から実装までの考え方
|
|
11
|
+
|
|
12
|
+
Needs to Implementation Philosophy
|
|
13
|
+
|
|
14
|
+
本ドキュメントは、要求、要件、仕様、設計、実装という記述内容の違いと関係を整理します。
|
|
15
|
+
ここでいう概念は内容を区別するためのものであり、プロジェクトの工程、成果物の分類、実際の作成順を固定するものではありません。
|
|
16
|
+
本書は規範(must)ではなく、概念の定義と典型的な誤りを扱います。成果物ごとの記述規則は各 rulebook を正本とします。
|
|
17
|
+
|
|
18
|
+
**対象読者**
|
|
19
|
+
|
|
20
|
+
- 要求、要件、仕様、設計、実装の違いを整理する業務担当者、エンジニア、レビュー担当者
|
|
21
|
+
|
|
22
|
+
**この文書で分かること**
|
|
23
|
+
|
|
24
|
+
- 各概念の目的と対象、Why・What・How の関係、概念ごとの代表的なアンチパターン
|
|
25
|
+
|
|
26
|
+
**次に読む文書**
|
|
27
|
+
|
|
28
|
+
- 文書の分類・ライフサイクル・配置は [ドキュメント構成ガイド](../guides/docs-structure-guide.md)、具体的な成果物は [成果物リファレンス](../references/deliverables-reference.md) を参照してください。
|
|
29
|
+
- トラックの構成と実行順序は [トラック設計ガイド](../guides/track-design-guide.md) を参照してください。
|
|
30
|
+
|
|
31
|
+
**この文書が扱わないこと**
|
|
32
|
+
|
|
33
|
+
- プロダクトドキュメントとプロジェクトドキュメントの分類や配置
|
|
34
|
+
- プロジェクトで成果物を選定・検討する順序や GO/NOT GO の判断
|
|
35
|
+
- Schedule 上の実行順、担当者、日付、反復
|
|
36
|
+
|
|
37
|
+
要求から実装への関係は、Why を What に具体化し、What を How で実現する論理的なつながりを表します。実務では、検証や変更によって前の概念へ戻りながら反復します。
|
|
38
|
+
|
|
39
|
+
| 概念 | 本質 |
|
|
40
|
+
| ---- | ---------------------- |
|
|
41
|
+
| 要求 | なぜやりたいか |
|
|
42
|
+
| 要件 | 何を満たす必要があるか |
|
|
43
|
+
| 仕様 | どう振る舞うべきか |
|
|
44
|
+
| 設計 | どう実現するか |
|
|
45
|
+
| 実装 | 現実に適用・定着させる |
|
|
46
|
+
|
|
47
|
+
各概念の例は、共通サンプル文脈「駄菓子屋きぬや 販売管理システム構築」を用います。店主の祖母 算野きぬが記憶とノートで続けてきた販売・在庫・つけ管理を、孫の算野創太がシステムで支えるシナリオです。背景の詳細は [サンプル記述標準](../standards/sample-authoring-standard.md) の `共通サンプル文脈` を参照してください。
|
|
48
|
+
|
|
49
|
+
## 1. 概念全体対応表
|
|
50
|
+
|
|
51
|
+
| 用語 | 5W1H | 対象 | 定義 |
|
|
52
|
+
| ---------------------- | ---------------- | -------------- | -------------------- |
|
|
53
|
+
| 要求(Needs) | Why | 業務・人 | 目的・価値・困りごと |
|
|
54
|
+
| 要件(Requirements) | What(条件) | 業務+システム | 満たすべき条件 |
|
|
55
|
+
| 仕様(Specifications) | What(振る舞い) | 業務+システム | 振る舞いの定義 |
|
|
56
|
+
| 設計(Design) | How(方式) | 業務+システム | 実現方式・構造 |
|
|
57
|
+
| 実装(Implementation) | How(具現) | 業務+システム | 実行・適用 |
|
|
58
|
+
|
|
59
|
+
## 2. 概念横断で特に危険なアンチパターン
|
|
60
|
+
|
|
61
|
+
### 2.1. 典型的なアンチパターン
|
|
62
|
+
|
|
63
|
+
| 概念 | 典型的失敗 |
|
|
64
|
+
| ---- | ---------------------- |
|
|
65
|
+
| 要求 | 目的を言語化しない |
|
|
66
|
+
| 要件 | 条件を検証可能にしない |
|
|
67
|
+
| 仕様 | 振る舞いを曖昧にする |
|
|
68
|
+
| 設計 | 業務を設計しない |
|
|
69
|
+
| 実装 | 現場に適用しない |
|
|
70
|
+
|
|
71
|
+
### 2.2. 横断的なアンチパターン
|
|
72
|
+
|
|
73
|
+
| アンチパターン | 影響 |
|
|
74
|
+
| --------------------------------- | ---------------------- |
|
|
75
|
+
| Why → What → How のトレースがない | 変更に耐えない |
|
|
76
|
+
| 粒度が混在 | 読めない・更新できない |
|
|
77
|
+
| 用語定義がない | 人・AIともに誤解 |
|
|
78
|
+
| 非機能を後回し | 使えない完成品 |
|
|
79
|
+
|
|
80
|
+
### 2.3. 補足
|
|
81
|
+
|
|
82
|
+
多くの失敗は能力不足ではなく、目的(Why)・条件(What)・方法(How)を区別せずに進めてしまうことで起きます。地図を持たずに歩き出すと速く進める人ほど遠くまで迷うのと同じで、本書はその混乱を防ぐための思考の整理です。
|
|
83
|
+
|
|
84
|
+
## 3. 要求(Needs)
|
|
85
|
+
|
|
86
|
+
業務の目的・価値を定義する概念
|
|
87
|
+
|
|
88
|
+
| 観点 | 内容(駄菓子屋の例) |
|
|
89
|
+
| ------------ | -------------------------------- |
|
|
90
|
+
| 困りごと | 暗算や在庫管理がつらくなってきた |
|
|
91
|
+
| 続けたい理由 | 子どもとの交流、地域の居場所 |
|
|
92
|
+
| ゴール | 無理せず駄菓子屋を続けられること |
|
|
93
|
+
|
|
94
|
+
### 3.1. 要求のアンチパターン
|
|
95
|
+
|
|
96
|
+
| アンチパターン | 原因 | 起きる問題 | 駄菓子屋の例 |
|
|
97
|
+
| ---------------------------------- | -------------- | ------------------------ | -------------------------------------- |
|
|
98
|
+
| 要求を書いたつもりで「手段」を書く | WhyとHowの混同 | 目的が不明確 | 「タブレットを導入したい」が要求になる |
|
|
99
|
+
| 要求を一文スローガンで終わらせる | 合意の浅さ | 判断軸が残らない | 「店を続けたい」だけで理由がない |
|
|
100
|
+
| 要求をエンジニアに丸投げ | 役割誤解 | 価値が実装に反映されない | 「あとはいい感じに」 |
|
|
101
|
+
|
|
102
|
+
### 3.2. 補足
|
|
103
|
+
|
|
104
|
+
目的が明確に共有されていれば、航路や手段が変わっても航海を続けられます。要求の失敗はこの逆で、Why が文書として残らなければ、途中で正しさを判断できなくなります。
|
|
105
|
+
|
|
106
|
+
## 4. 要件(Requirements)
|
|
107
|
+
|
|
108
|
+
要求を満たすための条件を定義する概念
|
|
109
|
+
|
|
110
|
+
| 種別 | 要件(例) |
|
|
111
|
+
| ------------ | ------------------------------ |
|
|
112
|
+
| 業務要件 | 子どもを待たせないこと |
|
|
113
|
+
| 業務要件 | 会計ミスを防ぐこと |
|
|
114
|
+
| システム要件 | 合計金額を正しく算出できること |
|
|
115
|
+
| 制約・前提 | 機械が苦手でも使えること |
|
|
116
|
+
|
|
117
|
+
制約・前提も要件として明文化します。
|
|
118
|
+
|
|
119
|
+
### 4.1. 要件のアンチパターン
|
|
120
|
+
|
|
121
|
+
| アンチパターン | 原因 | 起きる問題 | 駄菓子屋の例 |
|
|
122
|
+
| ------------------ | ------------- | ------------ | ------------------------ |
|
|
123
|
+
| 要件を飛ばす | 早く作りたい | スコープ崩壊 | いきなりUI設計に入る |
|
|
124
|
+
| 要件が抽象的 | 検証意識不足 | 受入不能 | 「簡単に使える」だけ |
|
|
125
|
+
| 要件に設計を混ぜる | Shall/How混同 | 変更不能 | 「SQLiteで在庫管理する」 |
|
|
126
|
+
|
|
127
|
+
### 4.2. 補足
|
|
128
|
+
|
|
129
|
+
測定できない条件は、管理も検証もできません。要件が検証可能な条件として定義されなければ、それは合意でも約束でもありません。要件の本質的な失敗は、満たすべき条件が検証可能でないことです。
|
|
130
|
+
|
|
131
|
+
## 5. 仕様(Specifications)
|
|
132
|
+
|
|
133
|
+
要件を満たすための振る舞いを定義する概念。業務仕様とシステム仕様を区別します。
|
|
134
|
+
業務仕様は、人の判断を含む現場のルールを定めます。システム仕様は、入力・状態・出力として観測可能な振る舞いを定めます。
|
|
135
|
+
|
|
136
|
+
### 5.1. 業務仕様(Business Specification)
|
|
137
|
+
|
|
138
|
+
| 条件 | 業務の振る舞い |
|
|
139
|
+
| -------------------------- | ------------------------ |
|
|
140
|
+
| 子どもが商品を持ってきたら | 店主が合計金額を提示する |
|
|
141
|
+
| お金が足りない場合 | 販売は成立しない |
|
|
142
|
+
| 販売成立時 | 在庫を減らす |
|
|
143
|
+
| 営業終了時 | その日の売上を確認する |
|
|
144
|
+
|
|
145
|
+
### 5.2. システム仕様(System Specification)
|
|
146
|
+
|
|
147
|
+
| 条件 | システムの振る舞い |
|
|
148
|
+
| ------------------ | ------------------ |
|
|
149
|
+
| 商品を選択したとき | 合計金額を表示する |
|
|
150
|
+
| 会計確定時 | 在庫数を1減らす |
|
|
151
|
+
| 在庫が0のとき | 選択不可とする |
|
|
152
|
+
| 日付変更時 | 日次売上を集計する |
|
|
153
|
+
|
|
154
|
+
### 5.3. 仕様のアンチパターン
|
|
155
|
+
|
|
156
|
+
(業務仕様・システム仕様)
|
|
157
|
+
|
|
158
|
+
| アンチパターン | 原因 | 起きる問題 | 駄菓子屋の例 |
|
|
159
|
+
| ---------------------- | ---------- | ---------- | ------------------------ |
|
|
160
|
+
| 業務仕様を書かない | 暗黙知前提 | 現場不適合 | 売上確認のやり方が未定義 |
|
|
161
|
+
| 画面仕様=仕様だと思う | 視覚偏重 | ルール抜け | 例外処理がない |
|
|
162
|
+
| 例外・境界を書かない | 正常系思考 | 現場停止 | お金が足りない時が未定義 |
|
|
163
|
+
|
|
164
|
+
### 5.4. 補足
|
|
165
|
+
|
|
166
|
+
「気をつけて運転する」という指示だけでは交通は成立せず、信号・優先・停止線といった具体的な振る舞いが定義されて初めてルールになります。仕様の本質的な失敗は、振る舞いを具体的に定義しないことです。
|
|
167
|
+
|
|
168
|
+
## 6. 設計(Design)
|
|
169
|
+
|
|
170
|
+
仕様をどう実現するかを決める概念。業務設計とシステム設計に分けて整理します。
|
|
171
|
+
|
|
172
|
+
| 観点 | 業務設計 | システム設計 |
|
|
173
|
+
| ---- | ---------------------- | ---------------------- |
|
|
174
|
+
| 会計 | 商品をまとめて一括会計 | 会計処理コンポーネント |
|
|
175
|
+
| 在庫 | 営業後に在庫確認 | 在庫管理データ構造 |
|
|
176
|
+
| 操作 | 声出し確認を行う | 大きなボタンUI |
|
|
177
|
+
| 責務 | 店主の判断を明確化 | 処理を自動化 |
|
|
178
|
+
|
|
179
|
+
### 6.1. 設計のアンチパターン
|
|
180
|
+
|
|
181
|
+
| アンチパターン | 原因 | 起きる問題 | 駄菓子屋の例 |
|
|
182
|
+
| ------------------ | -------- | ------------ | ---------------------------- |
|
|
183
|
+
| 設計=IT設計だけ | 業務軽視 | 業務が壊れる | 新レジ導入で会計が遅くなる |
|
|
184
|
+
| 設計で仕様を変更 | 概念逆転 | 合意崩壊 | 設計段階で会計ルールを変える |
|
|
185
|
+
| 将来変更を考えない | 近視眼 | 保守不能 | 商品追加が毎回改修 |
|
|
186
|
+
|
|
187
|
+
### 6.2. 補足
|
|
188
|
+
|
|
189
|
+
柵がなぜそこにあるか分からないうちは壊すべきでないのと同じで、仕様(What)を理解せずに設計(How)を変えると、本来守るべき目的まで壊してしまいます。設計の本質的な失敗は、How が勝手に What を書き換えることです。
|
|
190
|
+
|
|
191
|
+
## 7. 実装(Implementation)
|
|
192
|
+
|
|
193
|
+
設計した内容を現実に適用する概念。業務実装とシステム実装を区別します。
|
|
194
|
+
|
|
195
|
+
| 観点 | 業務実装 | システム実装 |
|
|
196
|
+
| ---- | ---------------------- | ---------------- |
|
|
197
|
+
| 会計 | 新しい会計手順に慣れる | 会計ロジック実装 |
|
|
198
|
+
| 在庫 | 紙メモをやめる | 在庫更新処理 |
|
|
199
|
+
| 運用 | 毎日売上を確認 | 日次集計機能 |
|
|
200
|
+
| 検証 | 実務で問題ないか | 単体・結合テスト |
|
|
201
|
+
|
|
202
|
+
### 7.1. 実装のアンチパターン
|
|
203
|
+
|
|
204
|
+
| アンチパターン | 原因 | 起きる問題 | 駄菓子屋の例 |
|
|
205
|
+
| ---------------- | ------------ | ---------- | -------------------- |
|
|
206
|
+
| 作ったら終わり | 業務実装軽視 | 使われない | 新手順の説明なし |
|
|
207
|
+
| 現場検証をしない | テスト偏重 | 運用事故 | 実際はボタンが小さい |
|
|
208
|
+
| 実装で仕様を補完 | 文書不足 | 属人化 | 例外対応を口頭で処理 |
|
|
209
|
+
|
|
210
|
+
### 7.2. 補足
|
|
211
|
+
|
|
212
|
+
処方箋が書かれただけでは患者を治さず、服用され継続されて初めて効果を持つのと同じで、設計した内容も現実に適用されなければ意味を持ちません。実装の本質的な失敗は、設計した内容が現実に適用されないことです。
|
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
---
|
|
2
|
+
specdojo:
|
|
3
|
+
id: specdojo:specdojo-philosophy
|
|
4
|
+
type: philosophy
|
|
5
|
+
status: draft
|
|
6
|
+
supersedes:
|
|
7
|
+
- documentation-philosophy
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# SpecDojo の考え方
|
|
11
|
+
|
|
12
|
+
SpecDojo Philosophy
|
|
13
|
+
|
|
14
|
+
SpecDojo の基本方針(Docs as Code / Kata・Waza・Ryu / Human & AI Readability)と、道場のメタファーである Kata・Waza・Ryu の関係、それらを構造化ドキュメントへ適用する設計・運用の原則、運用上の判断基準を示します。実行・エージェント固有の方針は各 guide を正本とします。
|
|
15
|
+
本書は規範(must)ではなく、規約の設計理由と判断原則を扱います。判定可能な規約は各 standard を正本とします。
|
|
16
|
+
|
|
17
|
+
**対象読者**
|
|
18
|
+
|
|
19
|
+
- SpecDojo の文書体系を設計・保守する利用者、standard・rulebook・guide の作成者
|
|
20
|
+
|
|
21
|
+
**この文書で分かること**
|
|
22
|
+
|
|
23
|
+
- 基本方針(Docs as Code / Kata・Waza・Ryu / Human & AI Readability)と、Kata・Waza・Ryu を分けて結び付ける理由、正本・構造化・メタデータ・規約と設定・トレーサビリティに関する設計理由と判断基準
|
|
24
|
+
|
|
25
|
+
**次に読む文書**
|
|
26
|
+
|
|
27
|
+
- 文書の分類と配置は [ドキュメント構成ガイド](../guides/docs-structure-guide.md)、メタデータの規定は [ドキュメントメタ情報標準](../standards/document-metadata-standard.md) を参照してください。
|
|
28
|
+
- Kata・Waza・Ryu それぞれの使い方は [実践の型活用ガイド](../guides/kata-guide.md)、[遂行の技活用ガイド](../guides/waza-guide.md)、[実践の進め方ガイド](../guides/ryu-guide.md) を参照してください。
|
|
29
|
+
|
|
30
|
+
## 1. 基本方針
|
|
31
|
+
|
|
32
|
+
SpecDojo の基本方針は次の3つです。「コードと同じ規律で管理し、型に沿って作成し、人と AI の双方が読める」ドキュメンテーションを目指します。
|
|
33
|
+
|
|
34
|
+
- **Docs as Code**: 正本を Git に置き、構造化・単一正本・生成・機械検証で、コードと同じ規律で管理する。
|
|
35
|
+
- **Kata・Waza・Ryu(型・技・流)**: 成果物の作り方を Kata(実践の型: rulebook / recipe / sample / template)として整え、Waza(遂行の技: `specdojo` CLI)で計画・実行・検証し、Ryu(流: `approach`)で型の整備状況と目的に応じた進め方を選ぶ。
|
|
36
|
+
- **Human & AI Readability**: 人が判断理由を理解でき、AI とツールが解析・生成・検証できる構造にする。
|
|
37
|
+
|
|
38
|
+
各方針を構造化ドキュメントへ適用する原則と判断基準は `ドキュメントの設計と運用の原則` にまとめます。Kata・Waza・Ryu の三つを分けて結び付ける理由は `道場のメタファー: Kata・Waza・Ryu` で示し、それぞれの詳細は各 guide を正本とします。
|
|
39
|
+
|
|
40
|
+
## 2. 道場のメタファー: Kata・Waza・Ryu
|
|
41
|
+
|
|
42
|
+
SpecDojo は、道場で技能を身につける構造になぞらえて、成果物の作り方に関わる三つの概念を分けて扱います。型を学び(Kata)、技で遂行し(Waza)、流派として進め方を選ぶ(Ryu)という関係です。三つの名称は説明のための愛称・分類であり、CLI のコマンド名、`approach` の値、frontmatter のフィールド名を変えるものではありません。
|
|
43
|
+
|
|
44
|
+
SpecDojo の特色は、この三つを別々の正本として保守しながら、機械的に結び付けている点にあります。内容の基準(Kata)、遂行の手段(Waza)、基準をどこまで使うかの判断(Ryu)を混ぜないことで、型が未整備でも作業を止めず、型が育てば同じ仕組みのまま作業の質が上がります。
|
|
45
|
+
|
|
46
|
+
### 2.1. 三つの概念と役割
|
|
47
|
+
|
|
48
|
+
| 概念 | 読み | 答える問い | SpecDojo 上の実体 | 正本 |
|
|
49
|
+
| ---- | ---- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
50
|
+
| Kata | 型 | この成果物には何を書き、どう作り、完成形はどうなるか | 実践の型: rulebook / recipe / sample / template | [実践体系構成ガイド](../guides/practice-system-composition-guide.md)、[実践の型活用ガイド](../guides/kata-guide.md) |
|
|
51
|
+
| Waza | 技 | 計画・実行・状態管理・機械検証をどう遂行するか | `specdojo` CLI: catalog / schedule / exec / register / routine / grade など | [遂行の技活用ガイド](../guides/waza-guide.md)、[CLIコマンドリファレンス](../references/command-reference.md) |
|
|
52
|
+
| Ryu | 流 | 型の整備状況と目的に応じて、型をどこまで基準にして進めるか | `approach`: fully-guided / recipe-guided / freeform と、retrofit / bootstrap / maintenance 系 / finalize 系 | [実践の進め方ガイド](../guides/ryu-guide.md)、[Schedule設計ガイド](../guides/schedule-design-guide.md) |
|
|
53
|
+
|
|
54
|
+
Kata は「何を・どう書くか」の基準を文書として持ちます。Waza は基準そのものを定義せず、成果物カタログから Schedule・タスク・plan・result へ展開して遂行し、結果を記録・検証します。Ryu は両者の間に立ち、今回のタスクで Kata をどこまで基準にするかを決めます。
|
|
55
|
+
|
|
56
|
+
### 2.2. 三つの関係
|
|
57
|
+
|
|
58
|
+
三つは一方向の階層ではなく、遂行の中で循環します。
|
|
59
|
+
|
|
60
|
+
```mermaid
|
|
61
|
+
flowchart LR
|
|
62
|
+
K["Kata(型)<br/>rulebook / recipe / sample / template"]
|
|
63
|
+
G["Waza: grade<br/>型の信頼度を判定"]
|
|
64
|
+
R["Ryu(流)<br/>目的と整備状況から approach を導出"]
|
|
65
|
+
E["Waza: exec<br/>plan に従い成果物を作成・更新"]
|
|
66
|
+
D["成果物"]
|
|
67
|
+
M["Ryu: maintenance 系<br/>成果物から型を見直す"]
|
|
68
|
+
|
|
69
|
+
K --> G --> R --> E --> D
|
|
70
|
+
D --> M --> K
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
- Waza の `grade` が Kata の内容を評価し、作成・更新の基準として信頼できるかを判定します。
|
|
74
|
+
- Ryu は、タスクの目的(strategy の `approach_rules`)と Kata の判定結果から `approach` を導きます。必要な型が揃い信頼できれば型を全面的に基準にし、recipe だけなら recipe を基準にし、頼れる型が無ければ型に縛られずに進めます。
|
|
75
|
+
- Waza の `exec` は、導かれた `approach` を plan に記録し、plan に従って成果物を作成・更新し、result と evidence を残します。
|
|
76
|
+
- 成果物が溜まると、maintenance 系の Ryu が成果物の実態から Kata を見直します。型は固定の規範ではなく、成果物との往復で育てる対象です。
|
|
77
|
+
|
|
78
|
+
この循環により、型の整備状況が変わっても手順を入れ替える必要はありません。同じ Waza のまま、Ryu の判断と Kata の内容だけが変わります。
|
|
79
|
+
|
|
80
|
+
### 2.3. 三つを分ける理由と判断基準
|
|
81
|
+
|
|
82
|
+
| 分ける組み合わせ | 分ける理由 | 分けない場合に起きること |
|
|
83
|
+
| ---------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
|
|
84
|
+
| Kata と Ryu | 型の有無や成熟度と、型をどこまで使うかの判断を独立させ、型が未整備でも作業を進められるようにする | 型に従うことを一律に求めると、未熟な型の誤りを成果物へ広げるか、型が揃うまで作業が止まる |
|
|
85
|
+
| Kata と Waza | 内容の基準を文書として保守し、CLI の実装や版に依存させない | 基準がコードや設定に埋もれ、ツールの変更が内容規約の変更になる。基準の理由を人が読めなくなる |
|
|
86
|
+
| Ryu と Waza | 進め方の判断を `approach` として明示し、plan に記録して再現・比較できるようにする | 参照度合いが実行者ごとの暗黙判断になり、人と AI、前回と今回で進め方が揃わず、結果の差を説明できない |
|
|
87
|
+
|
|
88
|
+
判断に迷った場合は、次を基準にします。
|
|
89
|
+
|
|
90
|
+
- 内容の正しさに関わる判断は Kata 側へ置きます。CLI に「何を書くべきか」を埋め込みません。
|
|
91
|
+
- 型をどこまで使うかの判断は Ryu の `approach` として表し、plan に残します。実行者が独自に参照範囲を広げたり狭めたりしません。
|
|
92
|
+
- 型が不足していると感じた場合は、型を強制するのでも無視するのでもなく、`approach` を見直すか、maintenance 系の Ryu で型そのものを育てます。
|
|
93
|
+
|
|
94
|
+
### 2.4. 典型的な誤り
|
|
95
|
+
|
|
96
|
+
| 誤り | 起きること | 判断の基準 |
|
|
97
|
+
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
98
|
+
| Kata を規範(must)と取り違える | 型の誤りがそのまま成果物へ広がる。型が無い成果物を作れなくなる | 型の信頼度は `grade` が判定し、どこまで従うかは Ryu が決める。規範は standard と rulebook |
|
|
99
|
+
| template だけを Kata と思う | 雛形を埋めるだけで、章構成の根拠(rulebook)や手順(recipe)、完成像(sample)が抜ける | Kata は4種で一組。それぞれが別の問いに答える |
|
|
100
|
+
| `approach` を固定値として扱う | 型が無い成果物に fully-guided を指定して実行が破綻する。型が育っても freeform のまま | `approach` は目的と整備状況から導く。strategy の生成結果に従う |
|
|
101
|
+
| 型が1件でも欠けることを理由に bootstrap を選ぶ | 不要な型まで一括で作られ、保守対象が膨らむ | 必要な型を作成条件に照らして決め、不要な型は `not-needed` と宣言する |
|
|
102
|
+
| Waza の生成物(generated、plan、result)を正本として編集する | 再生成で消える。正本と派生物の関係が崩れる | 正本は成果物と Kata。生成物は Waza が作り直す |
|
|
103
|
+
| Kata・Waza・Ryu を識別子と混同する | 存在しないコマンド名やフィールド名を探す | 三つは愛称・分類。実体は CLI のコマンド、`approach` の値、文書種別 |
|
|
104
|
+
|
|
105
|
+
## 3. ドキュメントの設計と運用の原則
|
|
106
|
+
|
|
107
|
+
SpecDojo のドキュメントは、単なる文章ではなく、プロジェクトを定義・管理・実行・検証するための構造化された情報資産として設計します。以下の 3.1 以降は、`基本方針` を実務へ落とすための設計判断と、判断に迷った場合に従う運用基準を一体で示した原則です。各原則がどの基本方針に対応するかは次のとおりです(括弧内は対応する広く知られた原則名)。
|
|
108
|
+
|
|
109
|
+
| 設計・運用の原則 | 対応する基本方針 |
|
|
110
|
+
| ---------------------------------------------------------------------------------- | ------------------------------------ |
|
|
111
|
+
| 3.1. 正本を一つに定め、他は参照・生成に寄せる(Single Source of Truth / DRY) | Docs as Code |
|
|
112
|
+
| 3.2. 人間とAIの両方が読める構造にする(Structured Documentation / AI Readability) | Docs as Code・Human & AI Readability |
|
|
113
|
+
| 3.3. ドキュメントを成果物として扱い、責務ごとに分ける | 横断(全方針) |
|
|
114
|
+
| 3.4. ファイル配置とIDで文書を識別できるようにする(ID as Identity / Traceability) | Docs as Code |
|
|
115
|
+
| 3.5. 規約と設定の責務を分ける(Convention as Defaults, Configuration) | Docs as Code |
|
|
116
|
+
| 3.6. 簡潔さと文章量を責務に合わせる(Concise but Complete) | Human & AI Readability |
|
|
117
|
+
| 3.7. 小さく始めて、必要に応じて拡張する | 横断(全方針) |
|
|
118
|
+
| 3.8. 変更理由を残す(Git as Source of Truth) | Docs as Code |
|
|
119
|
+
| 3.9. 例外は明示的に扱う | 横断(全方針) |
|
|
120
|
+
|
|
121
|
+
`3.3`・`3.7`・`3.9` は特定の基本方針というより、複数の方針を実務で適用するときに繰り返し必要になる横断的な判断基準です。Kata・Waza・Ryu は成果物の作り方と遂行に関する方針のため、本章の設計・運用原則ではなく `道場のメタファー: Kata・Waza・Ryu` で扱います。
|
|
122
|
+
|
|
123
|
+
### 3.1. 正本を一つに定め、他は参照・生成に寄せる
|
|
124
|
+
|
|
125
|
+
同じ情報を複数の場所で正として管理しません。情報ごとに正本となるドキュメントを一つ定め、そこから参照・要約・生成される派生ドキュメントを明確に分離します。
|
|
126
|
+
|
|
127
|
+
- 正本は、判断・承認・変更管理の対象とします。派生物は、一覧、ビュー、レポート、生成物として扱い、正本と異なる内容を直接記述しません。
|
|
128
|
+
- 一覧、集計、進捗ビュー、依存関係ビューなど、正本から機械的に導出できる情報は、可能な限り生成物として扱います。自動生成された文書は `generated` として区別し、直接編集する運用は避けます。
|
|
129
|
+
- 同じ情報が複数の場所に存在する場合は、どのドキュメントを正本とするかを先に決めます。既存の正本がある場合はそこを更新し、他の文書では参照・要約・抜粋にとどめます。要約は正本と矛盾しないようにし、古くなりやすい場合は要約ではなく参照に寄せます。
|
|
130
|
+
- 複数の文書を手作業で同期し続ける必要がある構成は避けます。生成できない場合でも正本と派生情報の関係を明記し、手作業で更新する場合は更新タイミングと責任を明確にします。
|
|
131
|
+
|
|
132
|
+
### 3.2. 人間とAIの両方が読める構造にする
|
|
133
|
+
|
|
134
|
+
ドキュメントは、人間が理解しやすく、AIやツールが解析しやすい構造で記述します。機械処理しやすさだけを優先して人間が読みにくい文書にせず、自由記述だけに依存してAIやツールが解析できない文書にもしません。
|
|
135
|
+
|
|
136
|
+
- 判断理由、背景、意図は Markdown の本文に記述し、状態、分類、参照、依存関係は構造化項目として記述します。
|
|
137
|
+
- 章構成は文書種別ごとの規約に従い、重要な属性は Frontmatter またはスキーマ所定の構造化項目として記述します。
|
|
138
|
+
- 表にした方が比較しやすい情報は表で記述し、長い表や一覧は必要に応じて YAML や生成物に分離します。
|
|
139
|
+
- 曖昧な表現だけでなく判定可能な記述を心がけ、AIが処理しやすいように同じ意味の項目名や表現は統一します。
|
|
140
|
+
|
|
141
|
+
形式ごとの役割とメタデータの持ち方は次のように分けます。
|
|
142
|
+
|
|
143
|
+
| 形式 | 主な役割 | メタデータの持ち方 |
|
|
144
|
+
| -------- | ---------------------------------------- | ------------------------------------------------ |
|
|
145
|
+
| Markdown | 説明、判断、方針、合意内容 | ファイル先頭の YAML Frontmatter |
|
|
146
|
+
| YAML | 人が作成・更新する管理データ、定義データ | ファイル先頭のトップレベル項目 |
|
|
147
|
+
| JSON | ツール連携、実行記録、機械生成データ | 用途別のスキーマが定めるトップレベルの構造化項目 |
|
|
148
|
+
|
|
149
|
+
メタデータを本文から分離して構造化することで、本文を解析しなくても文書の識別、分類、状態判定、参照解決、スキーマ検証を行えます。また、人が読む説明と、AI・ツールが使用する管理情報の責務を分け、表現の変更が識別や処理へ与える影響を抑えられます。
|
|
150
|
+
|
|
151
|
+
具体的な項目、必須条件、形式は
|
|
152
|
+
[ドキュメントメタ情報標準](../standards/document-metadata-standard.md)
|
|
153
|
+
を正本とします。
|
|
154
|
+
|
|
155
|
+
### 3.3. ドキュメントを成果物として扱い、責務ごとに分ける
|
|
156
|
+
|
|
157
|
+
ドキュメントは、作業の補助資料ではなく、プロジェクトの成果物として扱います。そのため、各ドキュメントには目的、責務、正本性、参照関係を明確に定め、一つのドキュメントに多くの責務を持たせすぎないようにします。
|
|
158
|
+
|
|
159
|
+
- 何を決定・説明・管理する文書かを明確にし、他の文書と責務が重複しないようにします。更新対象となる情報と、参照のみ行う情報を区別します。
|
|
160
|
+
- 成果物として管理すべき文書には、形式に応じたメタデータとして `id`、`type`、`status` などを付与します。
|
|
161
|
+
- 1文書には原則として1つの主目的を持たせ、大きくなりすぎる文書は索引文書と個別文書に分割します。分割した文書間では正本の所在と参照関係を明確にしますが、過度な分割により読者の理解を妨げないようにします。
|
|
162
|
+
- 構成や分割に迷った場合は、最終的な利用者が理解しやすい形を優先します。初めて読む人が文書の目的を理解できるか、関係者が必要な情報にたどり着けるかを確認し、参照が多すぎる場合は要約や索引を追加し、詳細が多すぎる場合は個別文書へ分割します。
|
|
163
|
+
|
|
164
|
+
### 3.4. ファイル配置とIDで文書を識別できるようにする
|
|
165
|
+
|
|
166
|
+
ドキュメントの同一性は、ファイル名ではなく、形式ごとに規定されたメタデータの `id` で判断します。ファイル名やディレクトリは、文書の正本識別子ではなく、可読性・分類・探索性を高めるための補助情報として扱います。
|
|
167
|
+
|
|
168
|
+
- ディレクトリは文書の責務やライフサイクルに基づいて分け、ファイル名は文書種別や対象を推測しやすい名前にします。入口となる文書には `*-index.md` を用い、個別文書には対象を表す語を含めます。
|
|
169
|
+
- 論理的な参照には `id` を用います。人間向けの本文リンクでは、必要に応じて相対パスを併用します。
|
|
170
|
+
- ファイル名や配置が変更されても、同じ文書であれば `id` は維持します。文書の意味や責務が大きく変わる場合は新しい `id` を付与し、旧文書との関係は `supersedes` などで明示します。
|
|
171
|
+
- 根拠文書は `based_on` などの構造化項目で明示し、参照関係の検証では原則として `id` を用います。
|
|
172
|
+
|
|
173
|
+
### 3.5. 規約と設定の責務を分ける
|
|
174
|
+
|
|
175
|
+
設定を減らすこと自体を目的にせず、共通の規約とプロジェクト固有の設定がそれぞれ一つの責務を持つようにします。
|
|
176
|
+
|
|
177
|
+
| 情報 | 管理方法 |
|
|
178
|
+
| ---------------------------------------------- | ------------------------ |
|
|
179
|
+
| ファイル命名、文書種別、メタデータ構造 | standard、rulebook |
|
|
180
|
+
| 標準パス、標準ステータス、設定省略時の既定動作 | 規約と既定値 |
|
|
181
|
+
| 対象プロジェクト、実際のパス、有効にする機能 | プロジェクト設定 |
|
|
182
|
+
| 使用するエージェント、権限、実行ポリシー | exec設定 |
|
|
183
|
+
| Schedule、メンバー、プロジェクト固有の選択 | 構造化された設定・成果物 |
|
|
184
|
+
|
|
185
|
+
- 複数のプロジェクトで共通かつ不変の構造は、規約または既定値として定義します。プロジェクト、環境、実行ごとに変わる選択は、設定として明示します。
|
|
186
|
+
- AI とツールは、設定が存在する場合は設定を正本として参照し、文書配置や周辺情報から推測して上書きしません。設定を省略できる項目には、規約で一意な既定値と解決順序を定めます。
|
|
187
|
+
- 設定はスキーマで検証し、許可する項目、型、列挙値を機械的に判定できるようにします。
|
|
188
|
+
- 規約の既定値を変更せず再記述するだけの設定や、同じ設定値を複数箇所で管理する構成は避けます。例外設定が必要な場合は、その理由、適用範囲、既定動作との差分を明示します。
|
|
189
|
+
|
|
190
|
+
### 3.6. 簡潔さと文章量を責務に合わせる
|
|
191
|
+
|
|
192
|
+
簡潔性は、必要な論点と判断根拠を維持し、重複と判断に不要な記述を除くことを指します。文字数や行数を減らすこと自体は目的にせず、文や項目の量は成果物種別、読者、リスク、説明責任に応じて判断します。
|
|
193
|
+
|
|
194
|
+
- 一文では一つの主張を扱い、条件、理由、結論が複数の主張に分かれる場合は文を分けます。
|
|
195
|
+
- 一段落では一つの論点を扱い、論点が変わる場合は段落または小見出しを分けます。
|
|
196
|
+
- 箇条書きでは一項目につき一つの判断、条件、または作業を示し、並列でない内容を同じ階層へ混在させません。
|
|
197
|
+
- 比較、対応、状態など、同じ項目で見比べる情報は表に置き、本文では表の全セルを言い換えず、表から読み取れない背景や判断理由だけを補います。
|
|
198
|
+
- 背景、判断理由、例外、制約、トレーサビリティ、`done_criteria` の充足に必要な内容は、短文化のために削除しません。
|
|
199
|
+
|
|
200
|
+
次の数値は見直しを始めるための推奨目安であり、一律の合格条件ではありません。
|
|
201
|
+
|
|
202
|
+
| 対象 | 推奨目安 | 目安を超えた場合の確認 |
|
|
203
|
+
| -------- | ----------------------------- | ------------------------------------------------------------------------ |
|
|
204
|
+
| 文 | 一文一主張 | 条件、理由、結論を分けても意味と因果関係が保てるか確認する |
|
|
205
|
+
| 段落 | 一論点、2〜4文程度 | 論点の混在、同じ主張の反復、小見出しへ分けられる内容がないか確認する |
|
|
206
|
+
| 箇条書き | 一項目一論点、1群3〜7項目程度 | 項目の分類、優先順位、表への変換、別節への分離が理解を助けるか確認する |
|
|
207
|
+
| 表 | 一行一対象または一判断 | 同じ対象の分散、セル内の複数論点、本文による表全体の再掲がないか確認する |
|
|
208
|
+
|
|
209
|
+
形式ごとの適用方法は次を推奨します。
|
|
210
|
+
|
|
211
|
+
| 形式 | 簡潔にする方法 | 保持する内容 |
|
|
212
|
+
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
|
|
213
|
+
| 文章中心の Markdown | 見出しごとに論点を分け、結論、理由、必要な補足を近接させる。詳細が別の正本にある場合は、必要最小限の要約と参照にする | 判断の背景、理由、例外、制約、読者が参照先を選ぶための文脈 |
|
|
214
|
+
| 表中心の Markdown | 一行の責務を統一し、本文では表の全内容を再掲しない。表全体に共通する前提や判断理由だけを本文へ置く | 行単位の識別、判定に必要な列、表だけでは表現しにくい共通の前提 |
|
|
215
|
+
| YAML / JSON | スキーマで許可されたフィールド、ID、参照で表現し、説明のためだけに項目を追加しない。詳細説明は責務を持つ文書へ委譲する | 必須フィールド、検証に必要な値、参照関係、スキーマ上の制約 |
|
|
216
|
+
|
|
217
|
+
文字数、行数、文数、項目数だけを理由に内容を削除したり、合否を判定したりしません。目安を超えていても、背景、判断理由、例外、制約、トレーサビリティ、`done_criteria` の充足に必要であれば保持し、必要に応じて文書分割や正本参照で読みやすさを改善します。
|
|
218
|
+
|
|
219
|
+
### 3.7. 小さく始めて、必要に応じて拡張する
|
|
220
|
+
|
|
221
|
+
ドキュメント体系は、最初からすべての文書種別、項目、ビューを揃えることを目的にせず、プロジェクトの規模、リスク、関係者数、変更頻度に応じて必要な文書を追加します。
|
|
222
|
+
|
|
223
|
+
- 必須項目は、識別、責務、状態、根拠、参照に関わるものを優先し、任意項目は必要になった段階で追加します。
|
|
224
|
+
- 小規模プロジェクトでは、同じ規約を保ったまま最小構成で開始します。複雑性が増した場合に文書や項目を分割・追加し、大規模プロジェクトでも同じ規約のまま拡張できるようにします。
|
|
225
|
+
- 使われていない文書や項目は見直し、追加した規約は既存文書との整合性を確認します。
|
|
226
|
+
|
|
227
|
+
### 3.8. 変更理由を残す
|
|
228
|
+
|
|
229
|
+
ドキュメントはGitで管理し、変更履歴を追跡可能にします。重要な変更では、何を変えたかだけでなく、なぜ変えたかが分かるようにします。
|
|
230
|
+
|
|
231
|
+
- 変更理由は、コミットメッセージ、Pull Request、または関連文書に残します。
|
|
232
|
+
- 意思決定に関わる変更は、根拠文書や判断記録と関連付けます。
|
|
233
|
+
- 仕様、スコープ、成果物、スケジュールに影響する変更は、影響範囲を確認します。
|
|
234
|
+
- 一時的な議論やメモは、必要に応じて正式な文書へ反映します。
|
|
235
|
+
|
|
236
|
+
### 3.9. 例外は明示的に扱う
|
|
237
|
+
|
|
238
|
+
規約から外れる場合は、暗黙的に処理せず、例外として明示します。
|
|
239
|
+
|
|
240
|
+
- なぜ規約に従わないのかを記録し、例外の適用範囲を限定します。
|
|
241
|
+
- 一時的な例外か、恒久的な例外かを区別します。
|
|
242
|
+
- 同じ例外が繰り返される場合は、規約自体の見直しを検討します。
|