universal-dev-standards 6.14.0-beta.9 → 6.14.1-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/uds.js +12 -1
- package/bundled/ai/options/commit-message/traditional-chinese.ai.yaml +69 -67
- package/bundled/ai/standards/commit-message.ai.yaml +12 -2
- package/bundled/ai/standards/mock-boundary.ai.yaml +138 -2
- package/bundled/ai/standards/secret-management-standards.ai.yaml +12 -1
- package/bundled/ai/standards/turn-completion-integrity.ai.yaml +6 -2
- package/bundled/core/commit-message-guide.md +22 -19
- package/bundled/core/mock-boundary.md +70 -2
- package/bundled/core/secret-management-standards.md +13 -1
- package/bundled/core/turn-completion-integrity.md +8 -2
- package/bundled/extensions/locales/zh-tw.md +19 -19
- package/bundled/hooks/check-dangerous-cmd.mjs +161 -26
- package/bundled/hooks/check-logging-standard.mjs +35 -6
- package/bundled/hooks/validate-commit-msg.mjs +317 -28
- package/bundled/locales/zh-CN/CHANGELOG.md +2323 -1099
- package/bundled/locales/zh-CN/CLAUDE.md +987 -101
- package/bundled/locales/zh-CN/README.md +3 -3
- package/bundled/locales/zh-CN/SECURITY.md +4 -3
- package/bundled/locales/zh-CN/STANDARDS-MAPPING.md +103 -6
- package/bundled/locales/zh-CN/adoption/ADOPTION-GUIDE.md +68 -97
- package/bundled/locales/zh-CN/adoption/DAILY-WORKFLOW-GUIDE.md +2 -1
- package/bundled/locales/zh-CN/adoption/STATIC-DYNAMIC-GUIDE.md +8 -9
- package/bundled/locales/zh-CN/adoption/checklists/enterprise.md +81 -80
- package/bundled/locales/zh-CN/adoption/checklists/minimal.md +18 -14
- package/bundled/locales/zh-CN/adoption/checklists/recommended.md +49 -46
- package/bundled/locales/zh-CN/ai/MAINTENANCE.md +44 -9
- package/bundled/locales/zh-CN/ai/options/commit-message/traditional-chinese.ai.yaml +63 -55
- package/bundled/locales/zh-CN/core/acceptance-criteria-traceability.md +61 -14
- package/bundled/locales/zh-CN/core/acceptance-test-driven-development.md +2 -1
- package/bundled/locales/zh-CN/core/accessibility-standards.md +871 -62
- package/bundled/locales/zh-CN/core/adr-standards.md +155 -32
- package/bundled/locales/zh-CN/core/agent-communication-protocol.md +2 -1
- package/bundled/locales/zh-CN/core/agent-dispatch.md +68 -33
- package/bundled/locales/zh-CN/core/ai-agreement-standards.md +23 -22
- package/bundled/locales/zh-CN/core/ai-command-behavior.md +2 -1
- package/bundled/locales/zh-CN/core/ai-friendly-architecture.md +311 -72
- package/bundled/locales/zh-CN/core/ai-instruction-standards.md +71 -49
- package/bundled/locales/zh-CN/core/ai-response-navigation.md +2 -1
- package/bundled/locales/zh-CN/core/alerting-standards.md +231 -36
- package/bundled/locales/zh-CN/core/anti-hallucination.md +116 -697
- package/bundled/locales/zh-CN/core/anti-sycophancy-prompting.md +34 -33
- package/bundled/locales/zh-CN/core/api-design-standards.md +144 -58
- package/bundled/locales/zh-CN/core/behavior-driven-development.md +2 -1
- package/bundled/locales/zh-CN/core/branch-completion.md +75 -20
- package/bundled/locales/zh-CN/core/capability-declaration.md +44 -94
- package/bundled/locales/zh-CN/core/change-batching-standards.md +2 -1
- package/bundled/locales/zh-CN/core/changelog-standards.md +485 -63
- package/bundled/locales/zh-CN/core/chaos-engineering-standards.md +141 -39
- package/bundled/locales/zh-CN/core/checkin-standards.md +176 -116
- package/bundled/locales/zh-CN/core/circuit-breaker.md +43 -77
- package/bundled/locales/zh-CN/core/code-review-checklist.md +37 -23
- package/bundled/locales/zh-CN/core/commit-message-guide.md +892 -69
- package/bundled/locales/zh-CN/core/containerization-standards.md +259 -57
- package/bundled/locales/zh-CN/core/context-aware-loading.md +103 -29
- package/bundled/locales/zh-CN/core/database-standards.md +115 -114
- package/bundled/locales/zh-CN/core/deprecation-standards.md +155 -40
- package/bundled/locales/zh-CN/core/design-document-standards.md +265 -55
- package/bundled/locales/zh-CN/core/developer-memory.md +150 -60
- package/bundled/locales/zh-CN/core/documentation-lifecycle.md +20 -16
- package/bundled/locales/zh-CN/core/documentation-structure.md +1284 -127
- package/bundled/locales/zh-CN/core/documentation-writing-standards.md +649 -259
- package/bundled/locales/zh-CN/core/dual-phase-output.md +37 -70
- package/bundled/locales/zh-CN/core/environment-standards.md +251 -73
- package/bundled/locales/zh-CN/core/error-code-standards.md +501 -60
- package/bundled/locales/zh-CN/core/estimation-standards.md +174 -41
- package/bundled/locales/zh-CN/core/execution-history.md +2 -1
- package/bundled/locales/zh-CN/core/failure-source-taxonomy.md +71 -84
- package/bundled/locales/zh-CN/core/feature-flag-standards.md +202 -57
- package/bundled/locales/zh-CN/core/forward-derivation-standards.md +613 -154
- package/bundled/locales/zh-CN/core/frontend-design-standards.md +361 -78
- package/bundled/locales/zh-CN/core/git-workflow.md +148 -262
- package/bundled/locales/zh-CN/core/git-worktree.md +59 -26
- package/bundled/locales/zh-CN/core/guides/file-placement-guide.md +132 -48
- package/bundled/locales/zh-CN/core/guides/performance-guide.md +61 -59
- package/bundled/locales/zh-CN/core/guides/security-guide.md +2 -0
- package/bundled/locales/zh-CN/core/health-check-standards.md +46 -104
- package/bundled/locales/zh-CN/core/immutability-first.md +83 -60
- package/bundled/locales/zh-CN/core/knowledge-transfer-standards.md +94 -31
- package/bundled/locales/zh-CN/core/mock-boundary.md +74 -6
- package/bundled/locales/zh-CN/core/mutation-testing.md +45 -6
- package/bundled/locales/zh-CN/core/observability-standards.md +281 -37
- package/bundled/locales/zh-CN/core/performance-standards.md +402 -42
- package/bundled/locales/zh-CN/core/pipeline-integration-standards.md +2 -1
- package/bundled/locales/zh-CN/core/postmortem-standards.md +358 -53
- package/bundled/locales/zh-CN/core/privacy-standards.md +148 -40
- package/bundled/locales/zh-CN/core/project-context-memory.md +182 -48
- package/bundled/locales/zh-CN/core/project-structure.md +550 -170
- package/bundled/locales/zh-CN/core/recovery-recipe-registry.md +54 -114
- package/bundled/locales/zh-CN/core/refactoring-standards.md +141 -556
- package/bundled/locales/zh-CN/core/requirement-engineering.md +7 -6
- package/bundled/locales/zh-CN/core/retrospective-standards.md +215 -22
- package/bundled/locales/zh-CN/core/retry-standards.md +46 -101
- package/bundled/locales/zh-CN/core/reverse-engineering-standards.md +370 -120
- package/bundled/locales/zh-CN/core/runbook-standards.md +294 -48
- package/bundled/locales/zh-CN/core/security-decision.md +45 -70
- package/bundled/locales/zh-CN/core/security-standards.md +169 -16
- package/bundled/locales/zh-CN/core/skill-standard-alignment-check.md +105 -71
- package/bundled/locales/zh-CN/core/slo-standards.md +296 -44
- package/bundled/locales/zh-CN/core/spec-driven-development.md +37 -6
- package/bundled/locales/zh-CN/core/standard-admission-criteria.md +25 -31
- package/bundled/locales/zh-CN/core/standard-lifecycle-management.md +49 -57
- package/bundled/locales/zh-CN/core/structured-task-definition.md +2 -1
- package/bundled/locales/zh-CN/core/supply-chain-security-standards.md +159 -32
- package/bundled/locales/zh-CN/core/systematic-debugging.md +87 -42
- package/bundled/locales/zh-CN/core/tech-debt-standards.md +202 -86
- package/bundled/locales/zh-CN/core/test-completeness-dimensions.md +262 -190
- package/bundled/locales/zh-CN/core/test-data-standards.md +252 -30
- package/bundled/locales/zh-CN/core/test-driven-development.md +21 -1022
- package/bundled/locales/zh-CN/core/test-governance.md +94 -43
- package/bundled/locales/zh-CN/core/testing-standards.md +83 -37
- package/bundled/locales/zh-CN/core/timeout-standards.md +45 -85
- package/bundled/locales/zh-CN/core/token-budget.md +44 -80
- package/bundled/locales/zh-CN/core/translation-lifecycle-standards.md +48 -36
- package/bundled/locales/zh-CN/core/turn-completion-integrity.md +8 -6
- package/bundled/locales/zh-CN/core/verification-evidence.md +44 -22
- package/bundled/locales/zh-CN/core/versioning.md +737 -73
- package/bundled/locales/zh-CN/core/virtual-organization-standards.md +30 -29
- package/bundled/locales/zh-CN/core/workflow-enforcement.md +9 -8
- package/bundled/locales/zh-CN/core/workflow-state-protocol.md +9 -8
- package/bundled/locales/zh-CN/docs/CHEATSHEET.md +2 -1
- package/bundled/locales/zh-CN/docs/CLI-FLOW.md +2 -1
- package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +19 -10
- package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +8 -6
- package/bundled/locales/zh-CN/docs/STANDARDS-REFERENCE.md +2 -1
- package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +133 -132
- package/bundled/locales/zh-CN/docs/USER-MANUAL.md +11 -3
- package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md +5 -2
- package/bundled/locales/zh-CN/docs/specs/system/memory-adoption-strategy.md +2 -0
- package/bundled/locales/zh-CN/docs/user/FAQ.md +2 -0
- package/bundled/locales/zh-CN/docs/user/GETTING-STARTED.md +2 -0
- package/bundled/locales/zh-CN/docs/user/GLOSSARY.md +2 -0
- package/bundled/locales/zh-CN/docs/user/README.md +4 -2
- package/bundled/locales/zh-CN/docs/user/TROUBLESHOOTING.md +2 -0
- package/bundled/locales/zh-CN/integrations/codex/AGENTS.md +136 -2
- package/bundled/locales/zh-CN/integrations/codex/README.md +62 -10
- package/bundled/locales/zh-CN/integrations/gemini-cli/GEMINI.md +59 -1
- package/bundled/locales/zh-CN/integrations/gemini-cli/README.md +9 -2
- package/bundled/locales/zh-CN/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md +7 -1
- package/bundled/locales/zh-CN/integrations/github-copilot/README.md +8 -2
- package/bundled/locales/zh-CN/integrations/github-copilot/copilot-instructions.md +146 -12
- package/bundled/locales/zh-CN/integrations/github-copilot/skills-mapping.md +7 -1
- package/bundled/locales/zh-CN/integrations/google-antigravity/AGENTS.md +110 -3
- package/bundled/locales/zh-CN/integrations/google-antigravity/README.md +7 -1
- package/bundled/locales/zh-CN/integrations/opencode/AGENTS.md +140 -2
- package/bundled/locales/zh-CN/integrations/opencode/README.md +7 -1
- package/bundled/locales/zh-CN/integrations/opencode/skills-mapping.md +8 -2
- package/bundled/locales/zh-CN/integrations/openspec/AGENTS.md +46 -1
- package/bundled/locales/zh-CN/integrations/openspec/README.md +7 -1
- package/bundled/locales/zh-CN/integrations/spec-kit/AGENTS.md +20 -2
- package/bundled/locales/zh-CN/integrations/spec-kit/README.md +7 -1
- package/bundled/locales/zh-CN/options/changelog/auto-generated.md +2 -0
- package/bundled/locales/zh-CN/options/changelog/keep-a-changelog.md +2 -0
- package/bundled/locales/zh-CN/options/code-review/automated-review.md +2 -0
- package/bundled/locales/zh-CN/options/code-review/pair-programming.md +2 -0
- package/bundled/locales/zh-CN/options/commit-message/bilingual.md +139 -50
- package/bundled/locales/zh-CN/options/commit-message/english.md +159 -42
- package/bundled/locales/zh-CN/options/commit-message/traditional-chinese.md +156 -75
- package/bundled/locales/zh-CN/options/documentation/api-docs.md +3 -1
- package/bundled/locales/zh-CN/options/documentation/markdown-docs.md +2 -0
- package/bundled/locales/zh-CN/options/documentation/wiki-style.md +2 -0
- package/bundled/locales/zh-CN/options/git-workflow/gitflow.md +105 -77
- package/bundled/locales/zh-CN/options/git-workflow/github-flow.md +75 -57
- package/bundled/locales/zh-CN/options/git-workflow/merge-commit.md +155 -44
- package/bundled/locales/zh-CN/options/git-workflow/rebase-ff.md +168 -53
- package/bundled/locales/zh-CN/options/git-workflow/squash-merge.md +122 -37
- package/bundled/locales/zh-CN/options/git-workflow/trunk-based.md +108 -61
- package/bundled/locales/zh-CN/options/project-structure/dotnet.md +266 -47
- package/bundled/locales/zh-CN/options/project-structure/go.md +301 -43
- package/bundled/locales/zh-CN/options/project-structure/java.md +268 -48
- package/bundled/locales/zh-CN/options/project-structure/kotlin.md +2 -0
- package/bundled/locales/zh-CN/options/project-structure/nodejs.md +168 -51
- package/bundled/locales/zh-CN/options/project-structure/php.md +2 -0
- package/bundled/locales/zh-CN/options/project-structure/python.md +210 -52
- package/bundled/locales/zh-CN/options/project-structure/ruby.md +2 -0
- package/bundled/locales/zh-CN/options/project-structure/rust.md +2 -0
- package/bundled/locales/zh-CN/options/project-structure/swift.md +2 -0
- package/bundled/locales/zh-CN/options/testing/contract-testing.md +2 -0
- package/bundled/locales/zh-CN/options/testing/e2e-testing.md +227 -66
- package/bundled/locales/zh-CN/options/testing/industry-pyramid.md +2 -0
- package/bundled/locales/zh-CN/options/testing/integration-testing.md +185 -73
- package/bundled/locales/zh-CN/options/testing/istqb-framework.md +2 -0
- package/bundled/locales/zh-CN/options/testing/performance-testing.md +2 -0
- package/bundled/locales/zh-CN/options/testing/security-testing.md +2 -0
- package/bundled/locales/zh-CN/options/testing/system-testing.md +270 -96
- package/bundled/locales/zh-CN/options/testing/unit-testing.md +185 -71
- package/bundled/locales/zh-CN/skills/CONTRIBUTING.template.md +43 -42
- package/bundled/locales/zh-CN/skills/INTEGRATION-GUIDE.md +2 -1
- package/bundled/locales/zh-CN/skills/README.md +2 -1
- package/bundled/locales/zh-CN/skills/_shared/README.md +2 -1
- package/bundled/locales/zh-CN/skills/adr-assistant/guide.md +240 -4
- package/bundled/locales/zh-CN/skills/agents/README.md +180 -82
- package/bundled/locales/zh-CN/skills/agents/code-architect.md +3 -1
- package/bundled/locales/zh-CN/skills/agents/doc-writer.md +3 -1
- package/bundled/locales/zh-CN/skills/agents/reviewer.md +4 -2
- package/bundled/locales/zh-CN/skills/agents/spec-analyst.md +3 -1
- package/bundled/locales/zh-CN/skills/agents/test-specialist.md +3 -1
- package/bundled/locales/zh-CN/skills/ai-collaboration-standards/SKILL.md +91 -81
- package/bundled/locales/zh-CN/skills/ai-collaboration-standards/anti-hallucination.md +79 -59
- package/bundled/locales/zh-CN/skills/ai-collaboration-standards/certainty-labels.md +66 -40
- package/bundled/locales/zh-CN/skills/ai-friendly-architecture/SKILL.md +23 -36
- package/bundled/locales/zh-CN/skills/ai-instruction-standards/SKILL.md +217 -137
- package/bundled/locales/zh-CN/skills/api-design-assistant/SKILL.md +13 -2
- package/bundled/locales/zh-CN/skills/atdd-assistant/SKILL.md +16 -2
- package/bundled/locales/zh-CN/skills/atdd-assistant/acceptance-criteria-guide.md +2 -1
- package/bundled/locales/zh-CN/skills/atdd-assistant/atdd-workflow.md +98 -1
- package/bundled/locales/zh-CN/skills/atdd-assistant/guide.md +148 -132
- package/bundled/locales/zh-CN/skills/audit-assistant/SKILL.md +5 -2
- package/bundled/locales/zh-CN/skills/bdd-assistant/SKILL.md +16 -2
- package/bundled/locales/zh-CN/skills/bdd-assistant/bdd-workflow.md +2 -1
- package/bundled/locales/zh-CN/skills/bdd-assistant/gherkin-guide.md +2 -1
- package/bundled/locales/zh-CN/skills/bdd-assistant/guide.md +122 -121
- package/bundled/locales/zh-CN/skills/changelog-guide/SKILL.md +9 -2
- package/bundled/locales/zh-CN/skills/changelog-guide/guide.md +91 -88
- package/bundled/locales/zh-CN/skills/checkin-assistant/SKILL.md +12 -2
- package/bundled/locales/zh-CN/skills/checkin-assistant/guide.md +211 -210
- package/bundled/locales/zh-CN/skills/ci-cd-assistant/SKILL.md +14 -2
- package/bundled/locales/zh-CN/skills/code-review-assistant/SKILL.md +12 -2
- package/bundled/locales/zh-CN/skills/code-review-assistant/checkin-checklist.md +79 -78
- package/bundled/locales/zh-CN/skills/code-review-assistant/guide.md +119 -45
- package/bundled/locales/zh-CN/skills/code-review-assistant/review-checklist.md +89 -88
- package/bundled/locales/zh-CN/skills/commands/ac-coverage.md +43 -1
- package/bundled/locales/zh-CN/skills/commands/api-design.md +2 -1
- package/bundled/locales/zh-CN/skills/commands/atdd.md +71 -1
- package/bundled/locales/zh-CN/skills/commands/audit.md +2 -1
- package/bundled/locales/zh-CN/skills/commands/bdd.md +160 -62
- package/bundled/locales/zh-CN/skills/commands/changelog.md +36 -1
- package/bundled/locales/zh-CN/skills/commands/check.md +53 -1
- package/bundled/locales/zh-CN/skills/commands/checkin.md +45 -1
- package/bundled/locales/zh-CN/skills/commands/ci-cd.md +3 -2
- package/bundled/locales/zh-CN/skills/commands/code-review.md +41 -1
- package/bundled/locales/zh-CN/skills/commands/commit.md +56 -1
- package/bundled/locales/zh-CN/skills/commands/config.md +50 -1
- package/bundled/locales/zh-CN/skills/commands/coverage.md +43 -1
- package/bundled/locales/zh-CN/skills/commands/database.md +4 -3
- package/bundled/locales/zh-CN/skills/commands/derive-all.md +42 -1
- package/bundled/locales/zh-CN/skills/commands/derive-atdd.md +35 -1
- package/bundled/locales/zh-CN/skills/commands/derive-bdd.md +41 -1
- package/bundled/locales/zh-CN/skills/commands/derive-tdd.md +42 -1
- package/bundled/locales/zh-CN/skills/commands/derive.md +60 -4
- package/bundled/locales/zh-CN/skills/commands/dev-workflow.md +58 -8
- package/bundled/locales/zh-CN/skills/commands/discover.md +41 -1
- package/bundled/locales/zh-CN/skills/commands/docgen.md +37 -1
- package/bundled/locales/zh-CN/skills/commands/docs.md +136 -5
- package/bundled/locales/zh-CN/skills/commands/durable.md +4 -3
- package/bundled/locales/zh-CN/skills/commands/e2e.md +85 -1
- package/bundled/locales/zh-CN/skills/commands/guide.md +2 -1
- package/bundled/locales/zh-CN/skills/commands/incident.md +5 -4
- package/bundled/locales/zh-CN/skills/commands/init.md +57 -1
- package/bundled/locales/zh-CN/skills/commands/methodology.md +166 -77
- package/bundled/locales/zh-CN/skills/commands/metrics.md +3 -2
- package/bundled/locales/zh-CN/skills/commands/migrate.md +5 -4
- package/bundled/locales/zh-CN/skills/commands/observability.md +48 -3
- package/bundled/locales/zh-CN/skills/commands/pr.md +4 -3
- package/bundled/locales/zh-CN/skills/commands/refactor.md +76 -38
- package/bundled/locales/zh-CN/skills/commands/release.md +82 -1
- package/bundled/locales/zh-CN/skills/commands/requirement.md +40 -1
- package/bundled/locales/zh-CN/skills/commands/reverse-bdd.md +36 -1
- package/bundled/locales/zh-CN/skills/commands/reverse-sdd.md +44 -1
- package/bundled/locales/zh-CN/skills/commands/reverse-tdd.md +42 -1
- package/bundled/locales/zh-CN/skills/commands/reverse.md +43 -1
- package/bundled/locales/zh-CN/skills/commands/runbook.md +50 -3
- package/bundled/locales/zh-CN/skills/commands/scan.md +3 -2
- package/bundled/locales/zh-CN/skills/commands/sdd-retro.md +50 -1
- package/bundled/locales/zh-CN/skills/commands/sdd.md +182 -1
- package/bundled/locales/zh-CN/skills/commands/security.md +3 -2
- package/bundled/locales/zh-CN/skills/commands/slo.md +51 -3
- package/bundled/locales/zh-CN/skills/commands/tdd.md +74 -5
- package/bundled/locales/zh-CN/skills/commands/update.md +70 -8
- package/bundled/locales/zh-CN/skills/commit-standards/SKILL.md +4 -4
- package/bundled/locales/zh-CN/skills/commit-standards/conventional-commits.md +45 -44
- package/bundled/locales/zh-CN/skills/commit-standards/guide.md +172 -52
- package/bundled/locales/zh-CN/skills/commit-standards/language-options.md +50 -47
- package/bundled/locales/zh-CN/skills/contract-test-assistant/SKILL.md +2 -2
- package/bundled/locales/zh-CN/skills/contract-test-assistant/guide.md +76 -1
- package/bundled/locales/zh-CN/skills/database-assistant/SKILL.md +18 -5
- package/bundled/locales/zh-CN/skills/dev-methodology/SKILL.md +4 -2
- package/bundled/locales/zh-CN/skills/dev-methodology/create-methodology.md +2 -0
- package/bundled/locales/zh-CN/skills/dev-methodology/runtime.md +2 -0
- package/bundled/locales/zh-CN/skills/docs-generator/SKILL.md +16 -2
- package/bundled/locales/zh-CN/skills/docs-generator/guide.md +8 -7
- package/bundled/locales/zh-CN/skills/documentation-guide/SKILL.md +209 -184
- package/bundled/locales/zh-CN/skills/documentation-guide/documentation-structure.md +73 -72
- package/bundled/locales/zh-CN/skills/documentation-guide/readme-template.md +37 -36
- package/bundled/locales/zh-CN/skills/durable-execution-assistant/SKILL.md +28 -2
- package/bundled/locales/zh-CN/skills/e2e-assistant/SKILL.md +21 -6
- package/bundled/locales/zh-CN/skills/error-code-guide/SKILL.md +76 -95
- package/bundled/locales/zh-CN/skills/git-workflow-guide/SKILL.md +80 -87
- package/bundled/locales/zh-CN/skills/git-workflow-guide/branch-naming.md +44 -43
- package/bundled/locales/zh-CN/skills/git-workflow-guide/git-workflow.md +66 -65
- package/bundled/locales/zh-CN/skills/incident-response-assistant/SKILL.md +31 -13
- package/bundled/locales/zh-CN/skills/metrics-dashboard-assistant/SKILL.md +38 -2
- package/bundled/locales/zh-CN/skills/observability-assistant/SKILL.md +75 -1
- package/bundled/locales/zh-CN/skills/pr-automation-assistant/SKILL.md +32 -6
- package/bundled/locales/zh-CN/skills/project-discovery/SKILL.md +8 -2
- package/bundled/locales/zh-CN/skills/project-discovery/guide.md +158 -157
- package/bundled/locales/zh-CN/skills/project-structure-guide/SKILL.md +49 -46
- package/bundled/locales/zh-CN/skills/project-structure-guide/language-patterns.md +8 -7
- package/bundled/locales/zh-CN/skills/refactoring-assistant/SKILL.md +22 -2
- package/bundled/locales/zh-CN/skills/refactoring-assistant/guide.md +172 -171
- package/bundled/locales/zh-CN/skills/release-standards/SKILL.md +66 -23
- package/bundled/locales/zh-CN/skills/release-standards/changelog-format.md +42 -41
- package/bundled/locales/zh-CN/skills/release-standards/guide.md +51 -43
- package/bundled/locales/zh-CN/skills/release-standards/release-workflow.md +131 -95
- package/bundled/locales/zh-CN/skills/release-standards/semantic-versioning.md +62 -61
- package/bundled/locales/zh-CN/skills/requirement-assistant/SKILL.md +24 -15
- package/bundled/locales/zh-CN/skills/requirement-assistant/guide.md +88 -79
- package/bundled/locales/zh-CN/skills/requirement-assistant/requirement-checklist.md +128 -127
- package/bundled/locales/zh-CN/skills/requirement-assistant/requirement-writing.md +121 -120
- package/bundled/locales/zh-CN/skills/retrospective-assistant/guide.md +206 -2
- package/bundled/locales/zh-CN/skills/reverse-engineer/SKILL.md +2 -2
- package/bundled/locales/zh-CN/skills/reverse-engineer/bdd-extraction.md +2 -1
- package/bundled/locales/zh-CN/skills/reverse-engineer/guide.md +297 -173
- package/bundled/locales/zh-CN/skills/reverse-engineer/tdd-analysis.md +2 -1
- package/bundled/locales/zh-CN/skills/reverse-engineer/workflow.md +2 -1
- package/bundled/locales/zh-CN/skills/runbook-assistant/SKILL.md +9 -2
- package/bundled/locales/zh-CN/skills/security-assistant/SKILL.md +24 -6
- package/bundled/locales/zh-CN/skills/security-scan-assistant/SKILL.md +34 -10
- package/bundled/locales/zh-CN/skills/slo-assistant/SKILL.md +2 -1
- package/bundled/locales/zh-CN/skills/spec-derivation/SKILL.md +2 -2
- package/bundled/locales/zh-CN/skills/spec-driven-dev/guide.md +38 -6
- package/bundled/locales/zh-CN/skills/tdd-assistant/SKILL.md +16 -3
- package/bundled/locales/zh-CN/skills/tdd-assistant/guide.md +217 -156
- package/bundled/locales/zh-CN/skills/tdd-assistant/language-examples.md +727 -82
- package/bundled/locales/zh-CN/skills/tdd-assistant/tdd-workflow.md +396 -214
- package/bundled/locales/zh-CN/skills/test-coverage-assistant/SKILL.md +14 -5
- package/bundled/locales/zh-CN/skills/test-coverage-assistant/guide.md +25 -12
- package/bundled/locales/zh-CN/skills/testing-guide/testing-pyramid.md +99 -98
- package/bundled/locales/zh-CN/skills/testing-guide/testing-theory.md +3 -1
- package/bundled/locales/zh-CN/skills/tools/cline/README.md +2 -1
- package/bundled/locales/zh-CN/skills/tools/copilot/README.md +65 -18
- package/bundled/locales/zh-CN/skills/tools/copilot/copilot-instructions.md +2 -1
- package/bundled/locales/zh-CN/skills/tools/cursor/README.md +2 -1
- package/bundled/locales/zh-CN/skills/tools/windsurf/README.md +2 -1
- package/bundled/locales/zh-CN/skills/workflows/README.md +4 -2
- package/bundled/locales/zh-CN/templates/reverse-spec-template.md +50 -1
- package/bundled/locales/zh-TW/CHANGELOG.md +2323 -1128
- package/bundled/locales/zh-TW/CLAUDE.md +962 -76
- package/bundled/locales/zh-TW/README.md +3 -3
- package/bundled/locales/zh-TW/SECURITY.md +4 -3
- package/bundled/locales/zh-TW/STANDARDS-MAPPING.md +103 -6
- package/bundled/locales/zh-TW/adoption/ADOPTION-GUIDE.md +46 -93
- package/bundled/locales/zh-TW/adoption/DAILY-WORKFLOW-GUIDE.md +2 -1
- package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +3 -1
- package/bundled/locales/zh-TW/adoption/checklists/enterprise.md +10 -9
- package/bundled/locales/zh-TW/adoption/checklists/minimal.md +6 -2
- package/bundled/locales/zh-TW/adoption/checklists/recommended.md +7 -4
- package/bundled/locales/zh-TW/ai/MAINTENANCE.md +34 -14
- package/bundled/locales/zh-TW/ai/options/commit-message/traditional-chinese.ai.yaml +48 -40
- package/bundled/locales/zh-TW/core/acceptance-criteria-traceability.md +56 -10
- package/bundled/locales/zh-TW/core/acceptance-test-driven-development.md +2 -1
- package/bundled/locales/zh-TW/core/accessibility-standards.md +895 -46
- package/bundled/locales/zh-TW/core/adr-standards.md +2 -1
- package/bundled/locales/zh-TW/core/agent-communication-protocol.md +2 -1
- package/bundled/locales/zh-TW/core/agent-dispatch.md +102 -33
- package/bundled/locales/zh-TW/core/ai-agreement-standards.md +58 -41
- package/bundled/locales/zh-TW/core/ai-command-behavior.md +2 -1
- package/bundled/locales/zh-TW/core/ai-friendly-architecture.md +306 -67
- package/bundled/locales/zh-TW/core/ai-instruction-standards.md +16 -13
- package/bundled/locales/zh-TW/core/ai-response-navigation.md +3 -3
- package/bundled/locales/zh-TW/core/alerting-standards.md +257 -35
- package/bundled/locales/zh-TW/core/anti-hallucination.md +169 -40
- package/bundled/locales/zh-TW/core/anti-sycophancy-prompting.md +2 -1
- package/bundled/locales/zh-TW/core/api-design-standards.md +2 -1
- package/bundled/locales/zh-TW/core/behavior-driven-development.md +3 -17
- package/bundled/locales/zh-TW/core/branch-completion.md +130 -34
- package/bundled/locales/zh-TW/core/capability-declaration.md +41 -79
- package/bundled/locales/zh-TW/core/change-batching-standards.md +2 -1
- package/bundled/locales/zh-TW/core/changelog-standards.md +14 -9
- package/bundled/locales/zh-TW/core/chaos-engineering-standards.md +138 -36
- package/bundled/locales/zh-TW/core/checkin-standards.md +84 -26
- package/bundled/locales/zh-TW/core/circuit-breaker.md +48 -87
- package/bundled/locales/zh-TW/core/code-review-checklist.md +19 -7
- package/bundled/locales/zh-TW/core/commit-message-guide.md +218 -87
- package/bundled/locales/zh-TW/core/containerization-standards.md +259 -57
- package/bundled/locales/zh-TW/core/context-aware-loading.md +121 -27
- package/bundled/locales/zh-TW/core/database-standards.md +2 -1
- package/bundled/locales/zh-TW/core/deprecation-standards.md +139 -37
- package/bundled/locales/zh-TW/core/design-document-standards.md +265 -55
- package/bundled/locales/zh-TW/core/developer-memory.md +102 -12
- package/bundled/locales/zh-TW/core/documentation-lifecycle.md +2 -1
- package/bundled/locales/zh-TW/core/documentation-structure.md +17 -8
- package/bundled/locales/zh-TW/core/dual-phase-output.md +28 -90
- package/bundled/locales/zh-TW/core/environment-standards.md +250 -72
- package/bundled/locales/zh-TW/core/error-code-standards.md +17 -6
- package/bundled/locales/zh-TW/core/estimation-standards.md +177 -44
- package/bundled/locales/zh-TW/core/execution-history.md +2 -1
- package/bundled/locales/zh-TW/core/failure-source-taxonomy.md +59 -117
- package/bundled/locales/zh-TW/core/feature-flag-standards.md +202 -57
- package/bundled/locales/zh-TW/core/forward-derivation-standards.md +592 -133
- package/bundled/locales/zh-TW/core/frontend-design-standards.md +120 -8
- package/bundled/locales/zh-TW/core/git-workflow.md +197 -37
- package/bundled/locales/zh-TW/core/git-worktree.md +79 -49
- package/bundled/locales/zh-TW/core/guides/anti-hallucination-guide.md +234 -487
- package/bundled/locales/zh-TW/core/guides/file-placement-guide.md +86 -2
- package/bundled/locales/zh-TW/core/guides/git-workflow-guide.md +411 -464
- package/bundled/locales/zh-TW/core/guides/performance-guide.md +2 -0
- package/bundled/locales/zh-TW/core/guides/refactoring-guide.md +237 -484
- package/bundled/locales/zh-TW/core/guides/security-guide.md +2 -0
- package/bundled/locales/zh-TW/core/health-check-standards.md +46 -104
- package/bundled/locales/zh-TW/core/immutability-first.md +45 -85
- package/bundled/locales/zh-TW/core/knowledge-graph-memory.md +2 -1
- package/bundled/locales/zh-TW/core/knowledge-transfer-standards.md +103 -40
- package/bundled/locales/zh-TW/core/mock-boundary.md +74 -6
- package/bundled/locales/zh-TW/core/observability-standards.md +284 -40
- package/bundled/locales/zh-TW/core/performance-standards.md +387 -86
- package/bundled/locales/zh-TW/core/pipeline-integration-standards.md +2 -1
- package/bundled/locales/zh-TW/core/postmortem-standards.md +367 -36
- package/bundled/locales/zh-TW/core/privacy-standards.md +153 -46
- package/bundled/locales/zh-TW/core/project-context-memory.md +210 -31
- package/bundled/locales/zh-TW/core/project-structure.md +240 -19
- package/bundled/locales/zh-TW/core/recovery-recipe-registry.md +54 -114
- package/bundled/locales/zh-TW/core/refactoring-standards.md +153 -48
- package/bundled/locales/zh-TW/core/requirement-engineering.md +8 -37
- package/bundled/locales/zh-TW/core/retrospective-standards.md +127 -7
- package/bundled/locales/zh-TW/core/retry-standards.md +41 -105
- package/bundled/locales/zh-TW/core/reverse-engineering-standards.md +5 -1
- package/bundled/locales/zh-TW/core/runbook-standards.md +296 -23
- package/bundled/locales/zh-TW/core/secret-management-standards.md +12 -4
- package/bundled/locales/zh-TW/core/security-decision.md +43 -84
- package/bundled/locales/zh-TW/core/security-standards.md +204 -25
- package/bundled/locales/zh-TW/core/self-review-protocol.md +2 -1
- package/bundled/locales/zh-TW/core/skill-standard-alignment-check.md +103 -69
- package/bundled/locales/zh-TW/core/slo-standards.md +301 -49
- package/bundled/locales/zh-TW/core/spec-driven-development.md +36 -7
- package/bundled/locales/zh-TW/core/standard-admission-criteria.md +22 -28
- package/bundled/locales/zh-TW/core/standard-lifecycle-management.md +40 -48
- package/bundled/locales/zh-TW/core/structured-task-definition.md +2 -1
- package/bundled/locales/zh-TW/core/supply-chain-security-standards.md +137 -10
- package/bundled/locales/zh-TW/core/systematic-debugging.md +94 -38
- package/bundled/locales/zh-TW/core/tech-debt-standards.md +170 -54
- package/bundled/locales/zh-TW/core/test-completeness-dimensions.md +101 -12
- package/bundled/locales/zh-TW/core/test-data-standards.md +245 -23
- package/bundled/locales/zh-TW/core/test-driven-development.md +4 -1
- package/bundled/locales/zh-TW/core/test-governance.md +92 -32
- package/bundled/locales/zh-TW/core/testing-standards.md +61 -14
- package/bundled/locales/zh-TW/core/timeout-standards.md +45 -85
- package/bundled/locales/zh-TW/core/token-budget.md +41 -112
- package/bundled/locales/zh-TW/core/translation-lifecycle-standards.md +28 -16
- package/bundled/locales/zh-TW/core/turn-completion-integrity.md +8 -6
- package/bundled/locales/zh-TW/core/verification-evidence.md +2 -1
- package/bundled/locales/zh-TW/core/versioning.md +6 -2
- package/bundled/locales/zh-TW/core/virtual-organization-standards.md +42 -36
- package/bundled/locales/zh-TW/core/workflow-enforcement.md +2 -1
- package/bundled/locales/zh-TW/core/workflow-state-protocol.md +2 -1
- package/bundled/locales/zh-TW/docs/CHEATSHEET.md +2 -1
- package/bundled/locales/zh-TW/docs/CLI-FLOW.md +2 -1
- package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +12 -3
- package/bundled/locales/zh-TW/docs/DEV-WORKFLOW-MAPPING.md +2 -1
- package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +8 -6
- package/bundled/locales/zh-TW/docs/STANDARDS-REFERENCE.md +2 -1
- package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +2 -1
- package/bundled/locales/zh-TW/docs/USER-MANUAL.md +9 -1
- package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md +4 -1
- package/bundled/locales/zh-TW/docs/specs/system/memory-adoption-strategy.md +2 -0
- package/bundled/locales/zh-TW/docs/user/FAQ.md +2 -0
- package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md +2 -0
- package/bundled/locales/zh-TW/docs/user/GLOSSARY.md +2 -0
- package/bundled/locales/zh-TW/docs/user/README.md +2 -0
- package/bundled/locales/zh-TW/docs/user/TROUBLESHOOTING.md +2 -0
- package/bundled/locales/zh-TW/integrations/claude-code/README.md +2 -1
- package/bundled/locales/zh-TW/integrations/codex/AGENTS.md +136 -2
- package/bundled/locales/zh-TW/integrations/codex/README.md +7 -1
- package/bundled/locales/zh-TW/integrations/gemini-cli/GEMINI.md +59 -1
- package/bundled/locales/zh-TW/integrations/gemini-cli/README.md +8 -1
- package/bundled/locales/zh-TW/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md +7 -1
- package/bundled/locales/zh-TW/integrations/github-copilot/README.md +9 -3
- package/bundled/locales/zh-TW/integrations/github-copilot/copilot-instructions.md +146 -12
- package/bundled/locales/zh-TW/integrations/github-copilot/skills-mapping.md +7 -1
- package/bundled/locales/zh-TW/integrations/google-antigravity/AGENTS.md +110 -3
- package/bundled/locales/zh-TW/integrations/google-antigravity/README.md +7 -1
- package/bundled/locales/zh-TW/integrations/opencode/AGENTS.md +140 -2
- package/bundled/locales/zh-TW/integrations/opencode/README.md +7 -1
- package/bundled/locales/zh-TW/integrations/opencode/skills-mapping.md +8 -2
- package/bundled/locales/zh-TW/integrations/openspec/AGENTS.md +46 -1
- package/bundled/locales/zh-TW/integrations/openspec/README.md +7 -1
- package/bundled/locales/zh-TW/integrations/spec-kit/AGENTS.md +20 -2
- package/bundled/locales/zh-TW/integrations/spec-kit/README.md +7 -1
- package/bundled/locales/zh-TW/methodologies/guides/tdd-guide.md +584 -475
- package/bundled/locales/zh-TW/options/changelog/auto-generated.md +2 -0
- package/bundled/locales/zh-TW/options/changelog/keep-a-changelog.md +2 -0
- package/bundled/locales/zh-TW/options/code-review/automated-review.md +2 -0
- package/bundled/locales/zh-TW/options/code-review/pair-programming.md +2 -0
- package/bundled/locales/zh-TW/options/commit-message/bilingual.md +93 -5
- package/bundled/locales/zh-TW/options/commit-message/english.md +118 -1
- package/bundled/locales/zh-TW/options/commit-message/traditional-chinese.md +82 -1
- package/bundled/locales/zh-TW/options/documentation/api-docs.md +2 -0
- package/bundled/locales/zh-TW/options/documentation/markdown-docs.md +2 -0
- package/bundled/locales/zh-TW/options/documentation/wiki-style.md +2 -0
- package/bundled/locales/zh-TW/options/git-workflow/gitflow.md +99 -71
- package/bundled/locales/zh-TW/options/git-workflow/github-flow.md +68 -50
- package/bundled/locales/zh-TW/options/git-workflow/merge-commit.md +131 -20
- package/bundled/locales/zh-TW/options/git-workflow/rebase-ff.md +142 -27
- package/bundled/locales/zh-TW/options/git-workflow/squash-merge.md +100 -15
- package/bundled/locales/zh-TW/options/git-workflow/trunk-based.md +103 -56
- package/bundled/locales/zh-TW/options/project-structure/dotnet.md +233 -14
- package/bundled/locales/zh-TW/options/project-structure/go.md +270 -12
- package/bundled/locales/zh-TW/options/project-structure/java.md +235 -15
- package/bundled/locales/zh-TW/options/project-structure/kotlin.md +2 -0
- package/bundled/locales/zh-TW/options/project-structure/nodejs.md +136 -19
- package/bundled/locales/zh-TW/options/project-structure/php.md +2 -0
- package/bundled/locales/zh-TW/options/project-structure/python.md +177 -19
- package/bundled/locales/zh-TW/options/project-structure/ruby.md +2 -0
- package/bundled/locales/zh-TW/options/project-structure/rust.md +2 -0
- package/bundled/locales/zh-TW/options/project-structure/swift.md +2 -0
- package/bundled/locales/zh-TW/options/testing/contract-testing.md +2 -0
- package/bundled/locales/zh-TW/options/testing/e2e-testing.md +182 -21
- package/bundled/locales/zh-TW/options/testing/industry-pyramid.md +2 -0
- package/bundled/locales/zh-TW/options/testing/integration-testing.md +134 -22
- package/bundled/locales/zh-TW/options/testing/istqb-framework.md +2 -0
- package/bundled/locales/zh-TW/options/testing/performance-testing.md +2 -0
- package/bundled/locales/zh-TW/options/testing/security-testing.md +2 -0
- package/bundled/locales/zh-TW/options/testing/system-testing.md +175 -1
- package/bundled/locales/zh-TW/options/testing/unit-testing.md +123 -9
- package/bundled/locales/zh-TW/skills/CONTRIBUTING.template.md +3 -2
- package/bundled/locales/zh-TW/skills/INTEGRATION-GUIDE.md +2 -1
- package/bundled/locales/zh-TW/skills/README.md +2 -1
- package/bundled/locales/zh-TW/skills/_shared/README.md +2 -1
- package/bundled/locales/zh-TW/skills/ac-coverage/SKILL.md +15 -4
- package/bundled/locales/zh-TW/skills/adr-assistant/guide.md +123 -3
- package/bundled/locales/zh-TW/skills/agents/README.md +99 -1
- package/bundled/locales/zh-TW/skills/agents/code-architect.md +2 -0
- package/bundled/locales/zh-TW/skills/agents/doc-writer.md +2 -0
- package/bundled/locales/zh-TW/skills/agents/reviewer.md +3 -1
- package/bundled/locales/zh-TW/skills/agents/spec-analyst.md +2 -0
- package/bundled/locales/zh-TW/skills/agents/test-specialist.md +2 -0
- package/bundled/locales/zh-TW/skills/ai-collaboration-standards/SKILL.md +48 -37
- package/bundled/locales/zh-TW/skills/ai-collaboration-standards/anti-hallucination.md +22 -2
- package/bundled/locales/zh-TW/skills/ai-collaboration-standards/certainty-labels.md +29 -3
- package/bundled/locales/zh-TW/skills/ai-friendly-architecture/SKILL.md +23 -36
- package/bundled/locales/zh-TW/skills/ai-instruction-standards/SKILL.md +12 -36
- package/bundled/locales/zh-TW/skills/api-design-assistant/SKILL.md +21 -5
- package/bundled/locales/zh-TW/skills/atdd-assistant/SKILL.md +40 -15
- package/bundled/locales/zh-TW/skills/atdd-assistant/acceptance-criteria-guide.md +2 -1
- package/bundled/locales/zh-TW/skills/atdd-assistant/atdd-workflow.md +98 -1
- package/bundled/locales/zh-TW/skills/atdd-assistant/guide.md +24 -8
- package/bundled/locales/zh-TW/skills/audit-assistant/SKILL.md +8 -2
- package/bundled/locales/zh-TW/skills/bdd-assistant/SKILL.md +29 -6
- package/bundled/locales/zh-TW/skills/bdd-assistant/bdd-workflow.md +2 -1
- package/bundled/locales/zh-TW/skills/bdd-assistant/gherkin-guide.md +2 -1
- package/bundled/locales/zh-TW/skills/bdd-assistant/guide.md +9 -8
- package/bundled/locales/zh-TW/skills/changelog-guide/SKILL.md +12 -3
- package/bundled/locales/zh-TW/skills/changelog-guide/guide.md +11 -7
- package/bundled/locales/zh-TW/skills/checkin-assistant/SKILL.md +19 -3
- package/bundled/locales/zh-TW/skills/checkin-assistant/guide.md +5 -3
- package/bundled/locales/zh-TW/skills/ci-cd-assistant/SKILL.md +35 -16
- package/bundled/locales/zh-TW/skills/code-review-assistant/SKILL.md +19 -2
- package/bundled/locales/zh-TW/skills/code-review-assistant/checkin-checklist.md +2 -1
- package/bundled/locales/zh-TW/skills/code-review-assistant/guide.md +81 -6
- package/bundled/locales/zh-TW/skills/code-review-assistant/review-checklist.md +2 -1
- package/bundled/locales/zh-TW/skills/commands/ac-coverage.md +47 -2
- package/bundled/locales/zh-TW/skills/commands/api-design.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/atdd.md +80 -10
- package/bundled/locales/zh-TW/skills/commands/audit.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/bdd.md +114 -16
- package/bundled/locales/zh-TW/skills/commands/changelog.md +45 -9
- package/bundled/locales/zh-TW/skills/commands/check.md +74 -21
- package/bundled/locales/zh-TW/skills/commands/checkin.md +56 -11
- package/bundled/locales/zh-TW/skills/commands/ci-cd.md +2 -1
- package/bundled/locales/zh-TW/skills/commands/code-review.md +43 -2
- package/bundled/locales/zh-TW/skills/commands/commit.md +58 -4
- package/bundled/locales/zh-TW/skills/commands/config.md +52 -4
- package/bundled/locales/zh-TW/skills/commands/coverage.md +45 -4
- package/bundled/locales/zh-TW/skills/commands/database.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/derive-all.md +44 -2
- package/bundled/locales/zh-TW/skills/commands/derive-atdd.md +37 -2
- package/bundled/locales/zh-TW/skills/commands/derive-bdd.md +44 -3
- package/bundled/locales/zh-TW/skills/commands/derive-tdd.md +45 -3
- package/bundled/locales/zh-TW/skills/commands/derive.md +62 -5
- package/bundled/locales/zh-TW/skills/commands/dev-workflow.md +60 -9
- package/bundled/locales/zh-TW/skills/commands/discover.md +43 -2
- package/bundled/locales/zh-TW/skills/commands/docgen.md +39 -2
- package/bundled/locales/zh-TW/skills/commands/docs.md +139 -7
- package/bundled/locales/zh-TW/skills/commands/durable.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/e2e.md +86 -3
- package/bundled/locales/zh-TW/skills/commands/guide.md +4 -2
- package/bundled/locales/zh-TW/skills/commands/incident.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/init.md +72 -15
- package/bundled/locales/zh-TW/skills/commands/methodology.md +117 -28
- package/bundled/locales/zh-TW/skills/commands/metrics.md +2 -1
- package/bundled/locales/zh-TW/skills/commands/migrate.md +2 -1
- package/bundled/locales/zh-TW/skills/commands/observability.md +45 -2
- package/bundled/locales/zh-TW/skills/commands/pr.md +2 -1
- package/bundled/locales/zh-TW/skills/commands/refactor.md +54 -13
- package/bundled/locales/zh-TW/skills/commands/release.md +83 -2
- package/bundled/locales/zh-TW/skills/commands/requirement.md +41 -2
- package/bundled/locales/zh-TW/skills/commands/reverse-bdd.md +37 -2
- package/bundled/locales/zh-TW/skills/commands/reverse-sdd.md +45 -2
- package/bundled/locales/zh-TW/skills/commands/reverse-tdd.md +43 -2
- package/bundled/locales/zh-TW/skills/commands/reverse.md +44 -2
- package/bundled/locales/zh-TW/skills/commands/runbook.md +47 -2
- package/bundled/locales/zh-TW/skills/commands/scan.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/sdd-retro.md +52 -3
- package/bundled/locales/zh-TW/skills/commands/sdd.md +209 -28
- package/bundled/locales/zh-TW/skills/commands/security.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/slo.md +48 -2
- package/bundled/locales/zh-TW/skills/commands/tdd.md +71 -2
- package/bundled/locales/zh-TW/skills/commands/update.md +64 -2
- package/bundled/locales/zh-TW/skills/commit-standards/SKILL.md +2 -2
- package/bundled/locales/zh-TW/skills/commit-standards/conventional-commits.md +2 -1
- package/bundled/locales/zh-TW/skills/commit-standards/guide.md +137 -17
- package/bundled/locales/zh-TW/skills/commit-standards/language-options.md +21 -18
- package/bundled/locales/zh-TW/skills/contract-test-assistant/SKILL.md +2 -2
- package/bundled/locales/zh-TW/skills/contract-test-assistant/guide.md +81 -1
- package/bundled/locales/zh-TW/skills/database-assistant/SKILL.md +21 -5
- package/bundled/locales/zh-TW/skills/deploy-assistant/SKILL.md +2 -1
- package/bundled/locales/zh-TW/skills/dev-methodology/SKILL.md +4 -1
- package/bundled/locales/zh-TW/skills/dev-methodology/create-methodology.md +2 -0
- package/bundled/locales/zh-TW/skills/dev-methodology/runtime.md +2 -0
- package/bundled/locales/zh-TW/skills/docs-generator/SKILL.md +19 -2
- package/bundled/locales/zh-TW/skills/docs-generator/guide.md +4 -3
- package/bundled/locales/zh-TW/skills/documentation-guide/SKILL.md +67 -42
- package/bundled/locales/zh-TW/skills/documentation-guide/documentation-structure.md +2 -1
- package/bundled/locales/zh-TW/skills/documentation-guide/readme-template.md +2 -1
- package/bundled/locales/zh-TW/skills/durable-execution-assistant/SKILL.md +32 -3
- package/bundled/locales/zh-TW/skills/e2e-assistant/SKILL.md +25 -7
- package/bundled/locales/zh-TW/skills/error-code-guide/SKILL.md +17 -34
- package/bundled/locales/zh-TW/skills/git-workflow-guide/SKILL.md +33 -38
- package/bundled/locales/zh-TW/skills/git-workflow-guide/branch-naming.md +2 -1
- package/bundled/locales/zh-TW/skills/git-workflow-guide/git-workflow.md +2 -1
- package/bundled/locales/zh-TW/skills/incident-response-assistant/SKILL.md +35 -14
- package/bundled/locales/zh-TW/skills/journey-test-assistant/SKILL.md +2 -14
- package/bundled/locales/zh-TW/skills/knowledge-graph/SKILL.md +6 -2
- package/bundled/locales/zh-TW/skills/metrics-dashboard-assistant/SKILL.md +42 -3
- package/bundled/locales/zh-TW/skills/observability-assistant/SKILL.md +85 -18
- package/bundled/locales/zh-TW/skills/pr-automation-assistant/SKILL.md +27 -3
- package/bundled/locales/zh-TW/skills/project-discovery/SKILL.md +11 -3
- package/bundled/locales/zh-TW/skills/project-discovery/guide.md +5 -3
- package/bundled/locales/zh-TW/skills/project-discovery/workflow.md +2 -1
- package/bundled/locales/zh-TW/skills/project-structure-guide/SKILL.md +19 -16
- package/bundled/locales/zh-TW/skills/project-structure-guide/language-patterns.md +2 -1
- package/bundled/locales/zh-TW/skills/refactoring-assistant/SKILL.md +26 -3
- package/bundled/locales/zh-TW/skills/refactoring-assistant/guide.md +4 -2
- package/bundled/locales/zh-TW/skills/release-standards/SKILL.md +91 -45
- package/bundled/locales/zh-TW/skills/release-standards/changelog-format.md +4 -3
- package/bundled/locales/zh-TW/skills/release-standards/guide.md +14 -5
- package/bundled/locales/zh-TW/skills/release-standards/release-workflow.md +5 -1
- package/bundled/locales/zh-TW/skills/release-standards/semantic-versioning.md +2 -1
- package/bundled/locales/zh-TW/skills/requirement-assistant/SKILL.md +15 -6
- package/bundled/locales/zh-TW/skills/requirement-assistant/guide.md +18 -8
- package/bundled/locales/zh-TW/skills/requirement-assistant/requirement-checklist.md +2 -1
- package/bundled/locales/zh-TW/skills/requirement-assistant/requirement-writing.md +2 -1
- package/bundled/locales/zh-TW/skills/retrospective-assistant/guide.md +200 -6
- package/bundled/locales/zh-TW/skills/reverse-engineer/bdd-extraction.md +2 -1
- package/bundled/locales/zh-TW/skills/reverse-engineer/guide.md +161 -36
- package/bundled/locales/zh-TW/skills/reverse-engineer/tdd-analysis.md +2 -1
- package/bundled/locales/zh-TW/skills/reverse-engineer/workflow.md +2 -1
- package/bundled/locales/zh-TW/skills/runbook-assistant/SKILL.md +9 -1
- package/bundled/locales/zh-TW/skills/security-assistant/SKILL.md +25 -5
- package/bundled/locales/zh-TW/skills/security-scan-assistant/SKILL.md +34 -8
- package/bundled/locales/zh-TW/skills/skill-builder/SKILL.md +3 -21
- package/bundled/locales/zh-TW/skills/slo-assistant/SKILL.md +3 -1
- package/bundled/locales/zh-TW/skills/spec-derivation/SKILL.md +2 -1
- package/bundled/locales/zh-TW/skills/spec-driven-dev/guide.md +35 -2
- package/bundled/locales/zh-TW/skills/sweep/SKILL.md +2 -1
- package/bundled/locales/zh-TW/skills/tdd-assistant/SKILL.md +10 -2
- package/bundled/locales/zh-TW/skills/tdd-assistant/guide.md +68 -9
- package/bundled/locales/zh-TW/skills/tdd-assistant/language-examples.md +693 -47
- package/bundled/locales/zh-TW/skills/tdd-assistant/tdd-workflow.md +183 -1
- package/bundled/locales/zh-TW/skills/test-coverage-assistant/SKILL.md +15 -5
- package/bundled/locales/zh-TW/skills/test-coverage-assistant/guide.md +26 -13
- package/bundled/locales/zh-TW/skills/testing-guide/testing-pyramid.md +2 -1
- package/bundled/locales/zh-TW/skills/testing-guide/testing-theory.md +3 -1
- package/bundled/locales/zh-TW/skills/tools/cline/README.md +2 -1
- package/bundled/locales/zh-TW/skills/tools/copilot/README.md +65 -18
- package/bundled/locales/zh-TW/skills/tools/copilot/copilot-instructions.md +2 -1
- package/bundled/locales/zh-TW/skills/tools/cursor/README.md +2 -1
- package/bundled/locales/zh-TW/skills/tools/windsurf/README.md +2 -1
- package/bundled/locales/zh-TW/skills/workflows/README.md +11 -9
- package/bundled/locales/zh-TW/templates/reverse-spec-template.md +50 -1
- package/bundled/skills/.claude-plugin/plugin.json +71 -0
- package/bundled/skills/commit-standards/SKILL.md +2 -2
- package/bundled/skills/commit-standards/guide.md +3 -2
- package/bundled/skills/commit-standards/language-options.md +19 -17
- package/package.json +2 -2
- package/src/commands/audit.js +28 -1
- package/src/commands/check.js +72 -3
- package/src/commands/compile.js +37 -4
- package/src/commands/config.js +49 -24
- package/src/commands/init.js +78 -30
- package/src/commands/open-work.js +6 -2
- package/src/commands/release-messages.js +228 -0
- package/src/commands/release.js +127 -68
- package/src/commands/run-intent.js +11 -0
- package/src/commands/spec.js +4 -2
- package/src/commands/update.js +227 -47
- package/src/compilers/claude-code-compiler.js +9 -1
- package/src/config/ai-agent-paths.js +14 -1
- package/src/core/installed-formats.js +15 -0
- package/src/core/open-work-config.js +20 -1
- package/src/core/project-config.js +55 -0
- package/src/i18n/messages.js +106 -2
- package/src/installers/hooks-installer.js +1 -1
- package/src/installers/manifest-installer.js +1 -1
- package/src/installers/skills-installer.js +1 -1
- package/src/installers/standards-installer.js +3 -1
- package/src/mcp/server.js +9 -3
- package/src/prompts/init.js +26 -22
- package/src/reconciler/actual-state-scanner.js +2 -8
- package/src/reconciler/backup-locations.js +5 -0
- package/src/reconciler/backup-manager.js +19 -11
- package/src/reconciler/desired-state-calculator.js +89 -57
- package/src/reconciler/plan-executor.js +101 -8
- package/src/reconciler/recorded-versions.js +49 -0
- package/src/reconciler/relative-path.js +23 -0
- package/src/uninstallers/hook-uninstaller.js +9 -1
- package/src/uninstallers/skills-uninstaller.js +22 -3
- package/src/utils/available-standards-report.js +25 -4
- package/src/utils/available-standards.js +13 -3
- package/src/utils/build-manifest.js +1 -1
- package/src/utils/commit-message-judge.js +60 -13
- package/src/utils/friction-detector.js +23 -11
- package/src/utils/git-hooks.js +106 -4
- package/src/utils/integration-generator.js +95 -67
- package/src/utils/legacy-hook-migration.js +121 -2
- package/src/utils/open-work-tracking.mjs +105 -16
- package/src/utils/sdd-header.js +16 -4
- package/src/utils/skills-installer.js +2 -1
- package/src/utils/spinner.js +14 -4
- package/src/utils/standard-validator.js +3 -2
- package/standards-registry.json +10 -8
- package/bundled/locales/zh-TW/core/guides/testing-guide.md +0 -2280
|
@@ -2,209 +2,1296 @@
|
|
|
2
2
|
source: ../../../core/documentation-structure.md
|
|
3
3
|
source_version: 1.5.0
|
|
4
4
|
translation_version: 1.5.0
|
|
5
|
-
last_synced: 2026-
|
|
5
|
+
last_synced: 2026-10-16
|
|
6
|
+
source_hash: 453295968842
|
|
6
7
|
status: current
|
|
7
8
|
---
|
|
8
9
|
|
|
9
|
-
> **语言**: [English](../../../core/documentation-structure.md) | [简体中文](../../zh-TW/core/documentation-structure.md) | 简体中文
|
|
10
|
-
|
|
11
10
|
# 文档结构标准
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
12
|
+
> **语言**: [English](../../../core/documentation-structure.md) | [繁體中文](../../zh-TW/core/documentation-structure.md) | 简体中文
|
|
13
|
+
|
|
14
|
+
**Version**: 1.5.0
|
|
15
|
+
**Last Updated**: 2026-03-17
|
|
16
|
+
**Applicability**: 所有需要文档的软件项目
|
|
17
|
+
**Scope**: partial
|
|
18
|
+
**Industry Standards**: Diátaxis Framework (diataxis.fr)
|
|
19
|
+
**References**: [diataxis.fr](https://diataxis.fr/)
|
|
16
20
|
|
|
17
21
|
---
|
|
18
22
|
|
|
19
23
|
## 目的
|
|
20
24
|
|
|
21
|
-
|
|
25
|
+
本标准为软件项目定义了一致的文档结构,确保信息组织有序、可被发现且易于维护。
|
|
22
26
|
|
|
23
27
|
---
|
|
24
28
|
|
|
25
|
-
##
|
|
29
|
+
## 文档分类 (Diátaxis)
|
|
30
|
+
|
|
31
|
+
所有文档应根据 [Diátaxis framework](https://diataxis.fr/) 分为四种类型之一。这种明确的分类有助于读者找到正确的文档,并帮助编写者专注于正确的内容。
|
|
32
|
+
|
|
33
|
+
### 四种文档类型
|
|
26
34
|
|
|
27
|
-
|
|
35
|
+
| Type | Purpose | User Need | Orientation | Example |
|
|
36
|
+
|------|---------|-----------|-------------|---------|
|
|
37
|
+
| **Tutorial** | 面向学习 | “我想学习” | 实践步骤 | 入门指南、首个项目演练 |
|
|
38
|
+
| **How-to** | 面向任务 | “我想完成 X” | 实践步骤 | 部署指南、迁移检查清单 |
|
|
39
|
+
| **Reference** | 面向信息 | “我需要查阅 Y” | 理论知识 | API 参考、配置参数 |
|
|
40
|
+
| **Explanation** | 面向理解 | “我想理解为什么” | 理论知识 | 架构概览、ADR、设计原理 |
|
|
28
41
|
|
|
42
|
+
### 文档类型头部
|
|
43
|
+
|
|
44
|
+
在文档头部添加 `Document Type` 字段以进行明确分类:
|
|
45
|
+
|
|
46
|
+
```markdown
|
|
47
|
+
**Document Type**: Tutorial | How-to | Reference | Explanation
|
|
29
48
|
```
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
49
|
+
|
|
50
|
+
### 与标准文档的映射
|
|
51
|
+
|
|
52
|
+
| Standard Document | Diátaxis Type | Rationale |
|
|
53
|
+
|-------------------|---------------|-----------|
|
|
54
|
+
| README.md | Tutorial / How-to | 快速入门导向 |
|
|
55
|
+
| getting-started.md | Tutorial | 循序渐进式学习 |
|
|
56
|
+
| ARCHITECTURE.md | Explanation | 理解系统设计 |
|
|
57
|
+
| API Reference | Reference | 查阅端点 |
|
|
58
|
+
| DEPLOYMENT.md | How-to | 任务:部署系统 |
|
|
59
|
+
| MIGRATION.md | How-to | 任务:迁移系统 |
|
|
60
|
+
| ADR/ | Explanation | 理解决策 |
|
|
61
|
+
| troubleshooting.md | How-to | 任务:解决问题 |
|
|
62
|
+
| CHANGELOG.md | Reference | 查阅变更历史 |
|
|
63
|
+
| 流程文档 | Reference / Explanation | 理解数据流 |
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## LLM 发现文件
|
|
68
|
+
|
|
69
|
+
发布供外部使用之文档的项目应考虑提供针对 LLM 优化的发现文件,类似于搜索引擎的 `robots.txt`。
|
|
70
|
+
|
|
71
|
+
### llms.txt 标准
|
|
72
|
+
|
|
73
|
+
`llms.txt` 文件(放置在项目或站点根目录)为基于 LLM 的检索系统提供结构化索引。
|
|
74
|
+
|
|
75
|
+
**Format**:
|
|
76
|
+
|
|
77
|
+
```markdown
|
|
78
|
+
# Project Name
|
|
79
|
+
|
|
80
|
+
> Brief one-line description of the project.
|
|
81
|
+
|
|
82
|
+
## Documentation
|
|
83
|
+
|
|
84
|
+
- [Getting Started](docs/getting-started.md): Tutorial for new users
|
|
85
|
+
- [API Reference](docs/api-reference.md): Complete REST API documentation
|
|
86
|
+
- [Architecture](docs/architecture.md): System design and component overview
|
|
87
|
+
|
|
88
|
+
## Optional
|
|
89
|
+
|
|
90
|
+
- [CHANGELOG](CHANGELOG.md): Version history
|
|
91
|
+
- [Contributing](CONTRIBUTING.md): Contribution guidelines
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### 何时创建 llms.txt
|
|
95
|
+
|
|
96
|
+
| Scenario | Create llms.txt? | Rationale |
|
|
97
|
+
|----------|:-----------------:|-----------|
|
|
98
|
+
| 公开开源项目 | ✅ Yes | 帮助 AI 工具发现并建立文档索引 |
|
|
99
|
+
| 带有外部使用者的公开 API | ✅ Yes | 支持 AI 辅助的 API 集成 |
|
|
100
|
+
| 公司内部项目 | ⚪ Optional | 如果使用内部 AI 工具则很有用 |
|
|
101
|
+
| 私有/个人项目 | ❌ No | 无外部使用者 |
|
|
102
|
+
|
|
103
|
+
### 放置位置
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
project-root/
|
|
107
|
+
├── llms.txt # LLM discovery file
|
|
108
|
+
├── llms-full.txt # Optional: full concatenated docs
|
|
109
|
+
├── README.md
|
|
110
|
+
└── docs/
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- `llms.txt`:包含链接和描述的结构化索引
|
|
114
|
+
- `llms-full.txt`(可选):拼接成单一文件的完整文档,用于完整的上下文摄入
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## 标准文档结构
|
|
119
|
+
|
|
120
|
+
```
|
|
121
|
+
project-root/
|
|
122
|
+
├── README.md # Project overview (REQUIRED)
|
|
123
|
+
├── CONTRIBUTING.md # Contribution guidelines
|
|
124
|
+
├── CHANGELOG.md # Version history
|
|
125
|
+
├── LICENSE # License file
|
|
126
|
+
├── .claude/ or .standards/ # Development standards
|
|
127
|
+
│ ├── anti-hallucination.md
|
|
128
|
+
│ ├── checkin-standards.md
|
|
129
|
+
│ ├── commit-guide.md
|
|
130
|
+
│ └── ...
|
|
131
|
+
├── docs/ # Detailed documentation
|
|
132
|
+
│ ├── index.md # Documentation index
|
|
133
|
+
│ ├── getting-started.md # Quick start guide
|
|
134
|
+
│ ├── architecture.md # System architecture
|
|
135
|
+
│ ├── api-reference.md # API documentation
|
|
136
|
+
│ ├── deployment.md # Deployment guide
|
|
137
|
+
│ ├── troubleshooting.md # Common issues
|
|
138
|
+
│ ├── specs/ # Specification documents
|
|
139
|
+
│ │ ├── README.md # Specification index
|
|
140
|
+
│ │ ├── system/ # System design specifications
|
|
141
|
+
│ │ │ └── *.md # High-level architecture designs
|
|
142
|
+
│ │ └── {component}/ # Component-specific specifications
|
|
143
|
+
│ │ ├── design/ # Design specifications
|
|
144
|
+
│ │ └── {module}/ # Implementation specifications
|
|
145
|
+
│ ├── flows/ # Flow documentation
|
|
146
|
+
│ │ ├── README.md # Flow index (REQUIRED when >5 flows)
|
|
147
|
+
│ │ ├── templates/
|
|
148
|
+
│ │ │ └── flow-template.md
|
|
149
|
+
│ │ └── {module}/
|
|
150
|
+
│ │ └── {module}-flow.md
|
|
151
|
+
│ ├── ADR/ # Architecture Decision Records
|
|
152
|
+
│ │ ├── README.md
|
|
153
|
+
│ │ └── NNN-title.md
|
|
154
|
+
│ └── diagrams/ # Architecture diagrams
|
|
155
|
+
│ ├── system-overview.mmd
|
|
156
|
+
│ ├── data-flow.mmd
|
|
48
157
|
│ └── README.md
|
|
49
|
-
└── examples/
|
|
158
|
+
└── examples/ # Code examples
|
|
159
|
+
├── basic-usage/
|
|
160
|
+
├── advanced-usage/
|
|
50
161
|
└── README.md
|
|
51
162
|
```
|
|
52
163
|
|
|
53
164
|
---
|
|
54
165
|
|
|
55
|
-
##
|
|
166
|
+
## 文件命名规范
|
|
167
|
+
|
|
168
|
+
### 根目录文件
|
|
169
|
+
|
|
170
|
+
根级文档文件应使用 **UPPERCASE** 命名,以便 GitHub/GitLab 自动识别:
|
|
171
|
+
|
|
172
|
+
| File | Naming | Reason |
|
|
173
|
+
|------|--------|--------|
|
|
174
|
+
| `README.md` | UPPERCASE | GitHub/GitLab 在仓库页面自动展示 |
|
|
175
|
+
| `CONTRIBUTING.md` | UPPERCASE | GitHub 在创建 PR 时自动建立链接 |
|
|
176
|
+
| `CHANGELOG.md` | UPPERCASE | Keep a Changelog 约定 |
|
|
177
|
+
| `LICENSE` | UPPERCASE (no extension) | GitHub 自动检测许可证类型 |
|
|
178
|
+
| `CODE_OF_CONDUCT.md` | UPPERCASE | GitHub 社区标准 |
|
|
179
|
+
| `SECURITY.md` | UPPERCASE | GitHub 安全通告标准 |
|
|
180
|
+
|
|
181
|
+
### docs/ 目录文件
|
|
182
|
+
|
|
183
|
+
`docs/` 内的所有文件应使用 **lowercase-kebab-case**,以确保 URL 友好性:
|
|
184
|
+
|
|
185
|
+
✅ **Correct**:
|
|
186
|
+
```
|
|
187
|
+
docs/
|
|
188
|
+
├── index.md
|
|
189
|
+
├── getting-started.md
|
|
190
|
+
├── api-reference.md
|
|
191
|
+
└── user-guide.md
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
❌ **Incorrect**:
|
|
195
|
+
```
|
|
196
|
+
docs/
|
|
197
|
+
├── INDEX.md # Inconsistent casing
|
|
198
|
+
├── GettingStarted.md # PascalCase not URL-friendly
|
|
199
|
+
├── API_Reference.md # snake_case inconsistent
|
|
200
|
+
└── User Guide.md # Spaces cause URL issues
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
**Rationale**:
|
|
204
|
+
- 小写可避免跨操作系统(Windows 与 Linux)的大小写敏感问题
|
|
205
|
+
- 短横线命名(kebab-case)可生成简洁的 URL:`docs/getting-started` 对比 `docs/GettingStarted`
|
|
206
|
+
- 一致的命名可提高可发现性与自动化程度
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## 文档需求矩阵
|
|
211
|
+
|
|
212
|
+
> **See Also**: 有关包含详细内容要求和项目类型描述的完整文档需求矩阵,请参阅 [documentation-writing-standards.md](documentation-writing-standards.md#document-requirements-matrix)。
|
|
213
|
+
|
|
214
|
+
本标准定义了文档存放在何处(文件结构)。写作标准则定义了每份文档应包含什么内容。
|
|
215
|
+
|
|
216
|
+
**Quick Reference**(完整矩阵请参阅写作标准):
|
|
217
|
+
|
|
218
|
+
| Document | Primary Location |
|
|
219
|
+
|----------|------------------|
|
|
220
|
+
| README.md | 项目根目录 |
|
|
221
|
+
| ARCHITECTURE.md | `docs/` |
|
|
222
|
+
| API.md | `docs/` |
|
|
223
|
+
| DATABASE.md | `docs/` |
|
|
224
|
+
| DEPLOYMENT.md | `docs/` |
|
|
225
|
+
| MIGRATION.md | `docs/` |
|
|
226
|
+
| ADR/ | `docs/adr/` |
|
|
227
|
+
| CHANGELOG.md | 项目根目录 |
|
|
228
|
+
| flows/ | `docs/flows/` |
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## 交叉引用标准(新增)
|
|
233
|
+
|
|
234
|
+
### 为什么交叉引用很重要
|
|
235
|
+
|
|
236
|
+
孤立的文档会导致导航问题。交叉引用能够实现:
|
|
237
|
+
- 上下文发现
|
|
238
|
+
- 减少重复
|
|
239
|
+
- 保持信息一致
|
|
240
|
+
|
|
241
|
+
### 必需的交叉引用矩阵
|
|
242
|
+
|
|
243
|
+
添加新文档时,请更新相关文档的引用章节:
|
|
244
|
+
|
|
245
|
+
| 添加...时 | 必须更新 |
|
|
246
|
+
|----------------|-------------|
|
|
247
|
+
| `flows/*.md` | ARCHITECTURE.md、index.md、相关 API.md / DATABASE.md |
|
|
248
|
+
| `ADR/*.md` | index.md、ARCHITECTURE.md、MIGRATION.md |
|
|
249
|
+
| 任何新文档 | docs/index.md |
|
|
250
|
+
|
|
251
|
+
### 链接方向原则
|
|
252
|
+
|
|
253
|
+
1. **向上链接**:流程文档应链接到 ARCHITECTURE.md(全局视图)
|
|
254
|
+
2. **水平链接**:相关流程应相互链接(例如,sms-flow → credit-flow)
|
|
255
|
+
3. **向下链接**:架构文档应链接到流程索引
|
|
256
|
+
|
|
257
|
+
### 引用章节格式
|
|
258
|
+
|
|
259
|
+
每份文档末尾都应包含一个引用章节:
|
|
260
|
+
|
|
261
|
+
```markdown
|
|
262
|
+
## References
|
|
263
|
+
|
|
264
|
+
- [ARCHITECTURE.md](../ARCHITECTURE.md) - System architecture
|
|
265
|
+
- [Related Flow](flows/xxx-flow.md) - Related flow documentation
|
|
266
|
+
- [API Reference](api-reference.md) - API specifications
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## 流程文档(新增)
|
|
272
|
+
|
|
273
|
+
### 目的
|
|
274
|
+
|
|
275
|
+
流程文档描述动态系统行为——即在特定操作期间数据如何在组件之间流动。
|
|
276
|
+
|
|
277
|
+
### 何时创建流程文档
|
|
278
|
+
|
|
279
|
+
| 优先级 | 流程类型 | 判定标准 | 示例 |
|
|
280
|
+
|:--------:|-----------|----------|----------|
|
|
281
|
+
| **P0** | 财务 | 涉及计费、额度、退款 | 额度扣除、费用计算 |
|
|
282
|
+
| **P0** | 集成 | 外部系统 API 交互 | SSO 登录、网关集成 |
|
|
283
|
+
| **P1** | 核心业务 | 主要功能流程 | 消息发送、报表查询 |
|
|
284
|
+
| **P2** | 批处理 | 后台服务、定时任务 | 守护进程服务、清理任务 |
|
|
285
|
+
| **P3** | 管理 | 管理与维护功能 | 账户管理、系统配置 |
|
|
286
|
+
|
|
287
|
+
### 流程文档结构
|
|
288
|
+
|
|
289
|
+
```
|
|
290
|
+
docs/flows/
|
|
291
|
+
├── README.md # Flow index (REQUIRED when >5 flows)
|
|
292
|
+
├── templates/
|
|
293
|
+
│ └── flow-template.md # Standard template
|
|
294
|
+
└── {module}/
|
|
295
|
+
└── {module}-flow.md
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
### flows/README.md 要求
|
|
299
|
+
|
|
300
|
+
当拥有超过 5 份流程文档时,`flows/README.md` 是**必需的**,且必须包含:
|
|
301
|
+
|
|
302
|
+
| 章节 | 描述 | 必需 |
|
|
303
|
+
|---------|-------------|:--------:|
|
|
304
|
+
| 系统架构概览 | ASCII 或 Mermaid 图 | ✅ |
|
|
305
|
+
| 流程文档列表 | 包含状态(✅ 已完成 / 🚧 进行中 / ⏳ 计划中) | ✅ |
|
|
306
|
+
| 模块关系图 | 展示模块交互的 Mermaid 流程图 | ✅ |
|
|
307
|
+
| 状态码参考 | 集中定义以避免重复 | ⚪ |
|
|
308
|
+
| 目录结构 | 文件组织结构 | ✅ |
|
|
309
|
+
|
|
310
|
+
### 流程文档必需章节
|
|
311
|
+
|
|
312
|
+
| 章节 | 描述 | 必需 |
|
|
313
|
+
|---------|-------------|:--------:|
|
|
314
|
+
| 概述 | 目的、范围、前置/后置条件 | ✅ |
|
|
315
|
+
| 触发条件 | 何时/由何触发此流程 | ✅ |
|
|
316
|
+
| 组件 | 组件列表、关系、代码链接 | ✅ |
|
|
317
|
+
| 流程图 | 主流程的时序图 | ✅ |
|
|
318
|
+
| 步骤详情 | 每步的输入/输出/代码位置 | ✅ |
|
|
319
|
+
| 错误处理 | 错误码、重试机制 | ✅ |
|
|
320
|
+
| 数据变更 | 受影响的表 + DFD 图 | ✅ |
|
|
321
|
+
| 性能 | TPS、响应时间、瓶颈 | ⚪ |
|
|
322
|
+
| 监控 | 日志点、指标 | ⚪ |
|
|
323
|
+
| 引用 | 指向 API.md、DATABASE.md 的链接 | ✅ |
|
|
324
|
+
|
|
325
|
+
### 集中式状态码管理
|
|
326
|
+
|
|
327
|
+
**问题**:分散在各流程文档中的状态码会导致不一致。
|
|
328
|
+
|
|
329
|
+
**解决方案**:
|
|
330
|
+
|
|
331
|
+
1. **集中定义**在 `flows/README.md` 或 `DATABASE.md` 中
|
|
332
|
+
2. **在流程文档中引用**:仅列出相关状态码,并附上说明:
|
|
333
|
+
> 完整定义见 [flows/README.md](../README.md)
|
|
334
|
+
3. **版本控制**:状态码变更必须记录在 CHANGELOG.md 中
|
|
335
|
+
|
|
336
|
+
**状态码定义格式**:
|
|
337
|
+
|
|
338
|
+
```markdown
|
|
339
|
+
### Status Codes
|
|
340
|
+
|
|
341
|
+
| Code | Name | Description | Used By |
|
|
342
|
+
|------|------|-------------|---------|
|
|
343
|
+
| 0000 | Success | Operation successful | All modules |
|
|
344
|
+
| 9997 | AuthFailed | Authentication failed | API, WebService |
|
|
345
|
+
| 9998 | NotFound | Resource not found | All modules |
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
---
|
|
349
|
+
|
|
350
|
+
## 规格文档
|
|
351
|
+
|
|
352
|
+
### 目的
|
|
353
|
+
|
|
354
|
+
规格文档在编码**之前**定义设计与实现细节。它们不同于常规文档:
|
|
355
|
+
|
|
356
|
+
| 类型 | 目的 | 受众 | 编写时间 | 位置 |
|
|
357
|
+
|------|---------|----------|--------------|----------|
|
|
358
|
+
| **规格** | 定义要构建什么以及如何构建 | 开发者 | 实现之前 | `docs/specs/` |
|
|
359
|
+
| **文档** | 说明构建了什么 | 用户、开发者 | 实现之后 | `docs/` |
|
|
360
|
+
|
|
361
|
+
### 规格目录结构
|
|
362
|
+
|
|
363
|
+
```
|
|
364
|
+
docs/specs/
|
|
365
|
+
├── README.md # Specification index (REQUIRED)
|
|
366
|
+
├── system/ # System-level design specifications
|
|
367
|
+
│ └── {feature}.md # High-level architecture designs
|
|
368
|
+
└── {component}/ # Component-specific specifications
|
|
369
|
+
├── design/ # Design specifications (pre-implementation)
|
|
370
|
+
├── shared/ # Cross-module shared specifications
|
|
371
|
+
└── {module}/ # Implementation specifications
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
### 规格类型
|
|
375
|
+
|
|
376
|
+
| 级别 | 描述 | 示例 | 位置 |
|
|
377
|
+
|-------|-------------|---------|----------|
|
|
378
|
+
| **系统规格** | 横切架构 | agents-workflows-system.md | `specs/system/` |
|
|
379
|
+
| **设计规格** | 组件设计决策 | ui-language-option.md | `specs/{component}/design/` |
|
|
380
|
+
| **实现规格** | 模块实现细节 | init/00-init-overview.md | `specs/{component}/{module}/` |
|
|
381
|
+
| **共享规格** | 跨模块工具 | manifest-schema.md | `specs/{component}/shared/` |
|
|
382
|
+
|
|
383
|
+
### 何时创建规格
|
|
384
|
+
|
|
385
|
+
| 场景 | 是否创建规格? | 类型 |
|
|
386
|
+
|----------|--------------|------|
|
|
387
|
+
| 包含多个组件的新功能 | 是 | 系统或设计 |
|
|
388
|
+
| 新 CLI 命令 | 是 | 实现 |
|
|
389
|
+
| 跨模块工具 | 是 | 共享 |
|
|
390
|
+
| Bug 修复 | 否 | - |
|
|
391
|
+
| 重构(行为不变) | 否 | - |
|
|
392
|
+
|
|
393
|
+
### 规格文件格式
|
|
394
|
+
|
|
395
|
+
每份规格文档都应包含:
|
|
396
|
+
|
|
397
|
+
```markdown
|
|
398
|
+
# Feature Name Specification
|
|
399
|
+
|
|
400
|
+
**Feature ID**: COMPONENT-FEATURE-NNN
|
|
401
|
+
**Version**: 1.0.0
|
|
402
|
+
**Last Updated**: YYYY-MM-DD
|
|
403
|
+
**Status**: Draft | In Review | Approved | Implemented
|
|
404
|
+
|
|
405
|
+
## Overview
|
|
406
|
+
[Brief description of what this specification covers]
|
|
407
|
+
|
|
408
|
+
## Acceptance Criteria
|
|
409
|
+
[AC-1, AC-2, ... with Given-When-Then format]
|
|
410
|
+
|
|
411
|
+
## Technical Design
|
|
412
|
+
[Implementation details]
|
|
413
|
+
|
|
414
|
+
## References
|
|
415
|
+
[Related specs and documentation]
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
### specs/README.md 要求
|
|
419
|
+
|
|
420
|
+
规格索引(`specs/README.md`)必须包含:
|
|
421
|
+
|
|
422
|
+
| 章节 | 描述 | 必需 |
|
|
423
|
+
|---------|-------------|:--------:|
|
|
424
|
+
| 目录结构 | 规格树状图 | ✅ |
|
|
425
|
+
| 系统规格 | 包含描述与状态的列表 | ✅ |
|
|
426
|
+
| 组件规格 | 按组件组织 | ✅ |
|
|
427
|
+
| 规格类型 | 类型定义与位置 | ⚪ |
|
|
428
|
+
| 相关文档 | 指向 docs/ 的链接 | ✅ |
|
|
429
|
+
|
|
430
|
+
---
|
|
431
|
+
|
|
432
|
+
## 索引文档标准
|
|
433
|
+
|
|
434
|
+
### docs/index.md 必要章节
|
|
435
|
+
|
|
436
|
+
| 章节 | 说明 | 必要 |
|
|
437
|
+
|---------|-------------|:--------:|
|
|
438
|
+
| 目录结构 | 文档树(ASCII 或表格) | ✅ |
|
|
439
|
+
| 按角色 | 开发者/审查者/管理员/QA 视角 | ⚪ |
|
|
440
|
+
| 按主题 | 架构/API/数据库/流程/迁移/ADR | ✅ |
|
|
441
|
+
| 流程文档 | flows/ 目录索引 | ✅(当存在流程时) |
|
|
442
|
+
| 外部资源 | 相关技术文档链接 | ⚪ |
|
|
443
|
+
| 维护指南 | 更新原则、贡献指南 | ⚪ |
|
|
444
|
+
| 最后更新 | 索引维护日期 | ✅ |
|
|
445
|
+
|
|
446
|
+
### 索引模板
|
|
447
|
+
|
|
448
|
+
```markdown
|
|
449
|
+
# Documentation Index
|
|
450
|
+
|
|
451
|
+
## Directory Structure
|
|
452
|
+
[Document tree diagram]
|
|
453
|
+
|
|
454
|
+
## By Topic
|
|
455
|
+
|
|
456
|
+
### Architecture
|
|
457
|
+
- [architecture.md](architecture.md) - System architecture
|
|
458
|
+
- [ADR/](ADR/) - Architecture Decision Records
|
|
459
|
+
|
|
460
|
+
### Flow Documentation
|
|
461
|
+
Located in `flows/`, full index at [flows/README.md](flows/README.md):
|
|
462
|
+
|
|
463
|
+
| Module | Document | Description |
|
|
464
|
+
|--------|----------|-------------|
|
|
465
|
+
| SMS | [sms-flow.md](flows/sms/sms-flow.md) | Message sending flow |
|
|
466
|
+
| Auth | [auth-flow.md](flows/auth/auth-flow.md) | Authentication flow |
|
|
467
|
+
|
|
468
|
+
---
|
|
469
|
+
*Last Updated: YYYY-MM-DD*
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
---
|
|
473
|
+
|
|
474
|
+
## CHANGELOG 文档集成(新增)
|
|
475
|
+
|
|
476
|
+
### 何时记录文档变更
|
|
477
|
+
|
|
478
|
+
| 变更类型 | 记录于 | 示例 |
|
|
479
|
+
|-------------|-----------|---------|
|
|
480
|
+
| 新文档 | Added | 新流程文档 `docs/flows/xxx.md` |
|
|
481
|
+
| 重大更新 | Changed | 使用 v2 API 规格更新 `docs/API.md` |
|
|
482
|
+
| 结构重组 | Changed | 重新组织 `docs/` 目录结构 |
|
|
483
|
+
| 弃用 | Deprecated | `docs/old-api.md` 标记为已弃用 |
|
|
484
|
+
| 移除 | Removed | 移除过时的 `docs/legacy.md` |
|
|
485
|
+
|
|
486
|
+
### 何时无需记录
|
|
487
|
+
|
|
488
|
+
- 错字修正
|
|
489
|
+
- 格式调整(缩进、空格)
|
|
490
|
+
- 链接修复
|
|
491
|
+
- 日期戳更新
|
|
492
|
+
|
|
493
|
+
### 记录格式
|
|
494
|
+
|
|
495
|
+
```markdown
|
|
496
|
+
## [Unreleased]
|
|
497
|
+
|
|
498
|
+
### Added
|
|
499
|
+
- New flow documentation (Mermaid sequence/flowchart/DFD)
|
|
500
|
+
- `docs/flows/README.md` - Flow index with module relationship diagram
|
|
501
|
+
- `docs/flows/sms/sms-flow.md` - SMS sending flow
|
|
502
|
+
|
|
503
|
+
### Changed
|
|
504
|
+
- Updated existing documents with flow references
|
|
505
|
+
- `docs/ARCHITECTURE.md` - Added flow index link in references
|
|
506
|
+
- `docs/index.md` - Added flow documentation section
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
---
|
|
510
|
+
|
|
511
|
+
## 核心文档文件
|
|
512
|
+
|
|
513
|
+
### 1. README.md(必需)
|
|
514
|
+
|
|
515
|
+
**目的**:第一印象、快速概览
|
|
516
|
+
|
|
517
|
+
**模板**:
|
|
518
|
+
```markdown
|
|
519
|
+
# Project Name
|
|
520
|
+
|
|
521
|
+
Brief one-liner description
|
|
522
|
+
|
|
523
|
+
## Features
|
|
524
|
+
|
|
525
|
+
- Feature 1
|
|
526
|
+
- Feature 2
|
|
527
|
+
- Feature 3
|
|
528
|
+
|
|
529
|
+
## Quick Start
|
|
530
|
+
|
|
531
|
+
```bash
|
|
532
|
+
# Installation
|
|
533
|
+
npm install your-package
|
|
534
|
+
|
|
535
|
+
# Usage
|
|
536
|
+
npm start
|
|
537
|
+
```
|
|
538
|
+
|
|
539
|
+
## Documentation
|
|
540
|
+
|
|
541
|
+
See [docs/](docs/) for full documentation.
|
|
542
|
+
|
|
543
|
+
## Contributing
|
|
544
|
+
|
|
545
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
546
|
+
|
|
547
|
+
## License
|
|
548
|
+
|
|
549
|
+
[License Name](LICENSE)
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
**必须包含**:
|
|
553
|
+
- [ ] 项目名称与描述
|
|
554
|
+
- [ ] 快速入门/安装
|
|
555
|
+
- [ ] 完整文档链接
|
|
556
|
+
- [ ] 许可证信息
|
|
557
|
+
|
|
558
|
+
---
|
|
559
|
+
|
|
560
|
+
### 2. CONTRIBUTING.md(推荐)
|
|
561
|
+
|
|
562
|
+
**目的**:如何为项目做出贡献
|
|
563
|
+
|
|
564
|
+
**模板**:
|
|
565
|
+
```markdown
|
|
566
|
+
# Contributing Guidelines
|
|
567
|
+
|
|
568
|
+
## Development Setup
|
|
569
|
+
|
|
570
|
+
```bash
|
|
571
|
+
git clone https://github.com/org/repo
|
|
572
|
+
cd repo
|
|
573
|
+
npm install
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
## Workflow
|
|
577
|
+
|
|
578
|
+
1. Fork the repository
|
|
579
|
+
2. Create feature branch: `git checkout -b feature/my-feature`
|
|
580
|
+
3. Commit changes: `git commit -m "feat: add feature"`
|
|
581
|
+
4. Push branch: `git push origin feature/my-feature`
|
|
582
|
+
5. Create pull request
|
|
583
|
+
|
|
584
|
+
## Coding Standards
|
|
585
|
+
|
|
586
|
+
- Follow [.claude/csharp-style.md](.claude/csharp-style.md)
|
|
587
|
+
- Run `npm run lint` before committing
|
|
588
|
+
- Ensure tests pass: `npm test`
|
|
589
|
+
|
|
590
|
+
## Commit Message Format
|
|
591
|
+
|
|
592
|
+
See [.claude/commit-guide.md](.claude/commit-guide.md)
|
|
593
|
+
|
|
594
|
+
## Code Review Process
|
|
595
|
+
|
|
596
|
+
See [.claude/code-review-checklist.md](.claude/code-review-checklist.md)
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
**必须包含**:
|
|
600
|
+
- [ ] 开发环境搭建说明
|
|
601
|
+
- [ ] 贡献工作流
|
|
602
|
+
- [ ] 代码规范参考
|
|
603
|
+
- [ ] 测试要求
|
|
604
|
+
|
|
605
|
+
---
|
|
606
|
+
|
|
607
|
+
### 3. CHANGELOG.md(推荐)
|
|
608
|
+
|
|
609
|
+
**目的**:跟踪版本间的变更
|
|
610
|
+
|
|
611
|
+
**格式**:遵循 [Keep a Changelog](https://keepachangelog.com/)
|
|
612
|
+
|
|
613
|
+
```markdown
|
|
614
|
+
# Changelog
|
|
615
|
+
|
|
616
|
+
## [Unreleased]
|
|
617
|
+
|
|
618
|
+
### Added
|
|
619
|
+
- New feature X
|
|
620
|
+
|
|
621
|
+
### Fixed
|
|
622
|
+
- Bug fix Y
|
|
623
|
+
|
|
624
|
+
## [1.2.0] - 2025-11-12
|
|
56
625
|
|
|
57
|
-
###
|
|
626
|
+
### Added
|
|
627
|
+
- OAuth2 authentication support
|
|
58
628
|
|
|
59
|
-
|
|
629
|
+
### Changed
|
|
630
|
+
- Updated API response format
|
|
631
|
+
|
|
632
|
+
### Deprecated
|
|
633
|
+
- Old API endpoint (will be removed in v2.0)
|
|
634
|
+
|
|
635
|
+
## [1.1.0] - 2025-10-01
|
|
636
|
+
|
|
637
|
+
### Added
|
|
638
|
+
- Email notification system
|
|
639
|
+
|
|
640
|
+
[Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD
|
|
641
|
+
[1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0
|
|
642
|
+
[1.1.0]: https://github.com/org/repo/releases/tag/v1.1.0
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
---
|
|
646
|
+
|
|
647
|
+
### 4. LICENSE(开源项目必需)
|
|
648
|
+
|
|
649
|
+
**常用许可证**:
|
|
650
|
+
- MIT:宽松型
|
|
651
|
+
- Apache 2.0:附带专利授权的宽松型
|
|
652
|
+
- GPL v3:Copyleft
|
|
653
|
+
- BSD:宽松型
|
|
654
|
+
- CC BY 4.0:文档/内容
|
|
655
|
+
|
|
656
|
+
---
|
|
657
|
+
|
|
658
|
+
## 文档版本对齐
|
|
659
|
+
|
|
660
|
+
### 原则
|
|
661
|
+
|
|
662
|
+
**文档版本必须与软件版本对齐。**
|
|
663
|
+
|
|
664
|
+
文档中的版本号表示“适用于软件版本 X.Y.Z”,而不是独立的文档修订版本号。
|
|
665
|
+
|
|
666
|
+
### 理由
|
|
667
|
+
|
|
668
|
+
| 方案 | 问题 |
|
|
60
669
|
|------|------|
|
|
61
|
-
|
|
|
62
|
-
|
|
|
63
|
-
|
|
64
|
-
|
|
670
|
+
| 独立文档版本 | 需要跟踪“哪个文档版本对应哪个软件版本”;容易混淆 |
|
|
671
|
+
| **对齐版本** ✓ | 清晰:文档 v1.2.0 = 适用于软件 v1.2.0 |
|
|
672
|
+
|
|
673
|
+
### 文档头部模板
|
|
674
|
+
|
|
675
|
+
```markdown
|
|
676
|
+
# Document Title
|
|
677
|
+
|
|
678
|
+
**Applicable Version**: 1.2.0 ← Aligned with software version
|
|
679
|
+
**Document Type**: [Guide/Reference/Specification]
|
|
680
|
+
**Target Audience**: [Developers/Operators/Users]
|
|
681
|
+
**Last Updated**: 2025-12-11 ← Date of last edit
|
|
682
|
+
|
|
683
|
+
---
|
|
684
|
+
```
|
|
685
|
+
|
|
686
|
+
### 字段定义
|
|
687
|
+
|
|
688
|
+
| 字段 | 必需 | 说明 |
|
|
689
|
+
|------|------|------|
|
|
690
|
+
| Applicable Version | ✅ 是 | 本文档适用的软件版本 |
|
|
691
|
+
| Document Type | 推荐 | 类别:指南、参考、规范、教程 |
|
|
692
|
+
| Target Audience | 推荐 | 目标读者 |
|
|
693
|
+
| Last Updated | ✅ 是 | 最后编辑日期 |
|
|
65
694
|
|
|
66
|
-
###
|
|
695
|
+
### 何时更新版本
|
|
67
696
|
|
|
68
|
-
|
|
|
697
|
+
| 场景 | 行动 |
|
|
69
698
|
|------|------|
|
|
70
|
-
|
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
699
|
+
| 软件发布包含功能变更的新版本 | 更新文档版本以保持匹配 |
|
|
700
|
+
| 文档微小错字修正(无软件变更) | 保留版本号,仅更新最后更新日期 |
|
|
701
|
+
| 文档针对即将发布的版本进行更新 | 使用新的版本号 |
|
|
702
|
+
|
|
703
|
+
### 示例
|
|
704
|
+
|
|
705
|
+
✅ **正确**:
|
|
706
|
+
```markdown
|
|
707
|
+
# Upgrade Guide
|
|
708
|
+
|
|
709
|
+
**Applicable Version**: 1.2.0
|
|
710
|
+
**Last Updated**: 2025-12-11
|
|
711
|
+
```
|
|
712
|
+
含义为:“在升级到 v1.2.0 时使用本指南”
|
|
713
|
+
|
|
714
|
+
❌ **错误**:
|
|
715
|
+
```markdown
|
|
716
|
+
# Upgrade Guide
|
|
717
|
+
|
|
718
|
+
**Version**: 1.1 ← Ambiguous: document revision or software version?
|
|
719
|
+
**Updated**: 2025-12-11
|
|
720
|
+
```
|
|
76
721
|
|
|
77
722
|
---
|
|
78
723
|
|
|
79
|
-
##
|
|
724
|
+
## 详细文档(`docs/`)
|
|
725
|
+
|
|
726
|
+
### docs/index.md
|
|
80
727
|
|
|
81
|
-
|
|
728
|
+
**目的**:所有文档的导航中心
|
|
82
729
|
|
|
730
|
+
**模板**:
|
|
83
731
|
```markdown
|
|
84
|
-
#
|
|
732
|
+
# Documentation Index
|
|
85
733
|
|
|
86
|
-
|
|
734
|
+
## By Role
|
|
87
735
|
|
|
88
|
-
|
|
736
|
+
### For Users
|
|
737
|
+
- [Getting Started](getting-started.md)
|
|
738
|
+
- [User Guide](user-guide.md)
|
|
739
|
+
- [FAQ](faq.md)
|
|
89
740
|
|
|
90
|
-
|
|
91
|
-
-
|
|
741
|
+
### For Developers
|
|
742
|
+
- [Architecture](architecture.md)
|
|
743
|
+
- [API Reference](api-reference.md)
|
|
744
|
+
- [Development Guide](development-guide.md)
|
|
92
745
|
|
|
93
|
-
|
|
746
|
+
### For Operators
|
|
747
|
+
- [Deployment Guide](deployment.md)
|
|
748
|
+
- [Configuration](configuration.md)
|
|
749
|
+
- [Troubleshooting](troubleshooting.md)
|
|
94
750
|
|
|
95
|
-
|
|
96
|
-
|
|
751
|
+
## By Topic
|
|
752
|
+
|
|
753
|
+
### Authentication
|
|
754
|
+
- [Architecture](architecture.md#authentication)
|
|
755
|
+
- [API Endpoints](api-reference.md#authentication)
|
|
756
|
+
|
|
757
|
+
### Database
|
|
758
|
+
- [Schema](architecture.md#database-schema)
|
|
759
|
+
- [Migrations](development-guide.md#database-migrations)
|
|
760
|
+
|
|
761
|
+
### Flow Documentation
|
|
762
|
+
See [flows/README.md](flows/README.md) for complete index.
|
|
763
|
+
|
|
764
|
+
## Quick Links
|
|
765
|
+
|
|
766
|
+
- [GitHub Repository](https://github.com/org/repo)
|
|
767
|
+
- [Issue Tracker](https://github.com/org/repo/issues)
|
|
768
|
+
- [Changelog](../CHANGELOG.md)
|
|
97
769
|
```
|
|
98
770
|
|
|
99
|
-
|
|
771
|
+
---
|
|
100
772
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
773
|
+
### docs/getting-started.md
|
|
774
|
+
|
|
775
|
+
**目的**:新用户快速入门
|
|
776
|
+
|
|
777
|
+
**结构**:
|
|
778
|
+
1. 前提条件
|
|
779
|
+
2. 安装
|
|
780
|
+
3. 基本配置
|
|
781
|
+
4. 第一个示例
|
|
782
|
+
5. 后续步骤
|
|
783
|
+
|
|
784
|
+
---
|
|
785
|
+
|
|
786
|
+
### docs/architecture.md
|
|
787
|
+
|
|
788
|
+
**目的**:系统设计与技术架构
|
|
789
|
+
|
|
790
|
+
**结构**:
|
|
791
|
+
1. 概述
|
|
792
|
+
2. 系统组件
|
|
793
|
+
3. 数据流
|
|
794
|
+
4. 设计决策
|
|
795
|
+
5. 技术栈
|
|
796
|
+
6. 安全架构
|
|
797
|
+
7. 性能考量
|
|
798
|
+
|
|
799
|
+
**包含图表**:
|
|
800
|
+
- 系统概述图
|
|
801
|
+
- 组件图
|
|
802
|
+
- 数据流图
|
|
803
|
+
- 部署图
|
|
804
|
+
|
|
805
|
+
**必须包含在参考中**:
|
|
806
|
+
- 链接至 `flows/README.md` 以获取详细的流程文档
|
|
807
|
+
|
|
808
|
+
---
|
|
809
|
+
|
|
810
|
+
### docs/api-reference.md
|
|
811
|
+
|
|
812
|
+
**目的**:完整的 API 文档
|
|
813
|
+
|
|
814
|
+
**结构**:
|
|
815
|
+
1. API 概述
|
|
816
|
+
2. 身份验证
|
|
817
|
+
3. 端点(按资源分组)
|
|
818
|
+
4. 请求/响应示例
|
|
819
|
+
5. 错误码
|
|
820
|
+
6. 速率限制
|
|
821
|
+
|
|
822
|
+
**端点模板**:
|
|
823
|
+
```markdown
|
|
824
|
+
## POST /api/users/authenticate
|
|
825
|
+
|
|
826
|
+
Authenticates a user and returns access token.
|
|
827
|
+
|
|
828
|
+
### Request
|
|
829
|
+
|
|
830
|
+
**Headers**:
|
|
831
|
+
```
|
|
832
|
+
Content-Type: application/json
|
|
104
833
|
```
|
|
105
834
|
|
|
106
|
-
|
|
835
|
+
**Body**:
|
|
836
|
+
```json
|
|
837
|
+
{
|
|
838
|
+
"username": "string",
|
|
839
|
+
"password": "string"
|
|
840
|
+
}
|
|
841
|
+
```
|
|
107
842
|
|
|
108
|
-
|
|
843
|
+
### Response
|
|
109
844
|
|
|
110
|
-
|
|
845
|
+
**Success (200 OK)**:
|
|
846
|
+
```json
|
|
847
|
+
{
|
|
848
|
+
"accessToken": "string",
|
|
849
|
+
"expiresIn": 3600
|
|
850
|
+
}
|
|
851
|
+
```
|
|
111
852
|
|
|
112
|
-
|
|
853
|
+
**Error (401 Unauthorized)**:
|
|
854
|
+
```json
|
|
855
|
+
{
|
|
856
|
+
"error": "INVALID_CREDENTIALS",
|
|
857
|
+
"message": "Invalid username or password"
|
|
858
|
+
}
|
|
859
|
+
```
|
|
113
860
|
|
|
114
|
-
|
|
861
|
+
### Examples
|
|
115
862
|
|
|
116
|
-
|
|
863
|
+
```bash
|
|
864
|
+
curl -X POST https://api.example.com/api/users/authenticate \
|
|
865
|
+
-H "Content-Type: application/json" \
|
|
866
|
+
-d '{"username":"user@example.com","password":"secret"}'
|
|
117
867
|
```
|
|
868
|
+
```
|
|
869
|
+
|
|
870
|
+
**必须包含在参考中**:
|
|
871
|
+
- 链接至相关流程文档(例如 `flows/auth/auth-flow.md`)
|
|
118
872
|
|
|
119
873
|
---
|
|
120
874
|
|
|
121
|
-
|
|
875
|
+
### docs/deployment.md
|
|
876
|
+
|
|
877
|
+
**目的**:如何部署应用程序
|
|
122
878
|
|
|
123
|
-
|
|
879
|
+
**结构**:
|
|
880
|
+
1. 前提条件
|
|
881
|
+
2. 环境搭建
|
|
882
|
+
3. 配置
|
|
883
|
+
4. 部署步骤
|
|
884
|
+
5. 验证
|
|
885
|
+
6. 回滚步骤
|
|
886
|
+
7. 监控
|
|
124
887
|
|
|
888
|
+
**必须包含在参考中**:
|
|
889
|
+
- 链接至相关守护进程/服务流程文档
|
|
890
|
+
|
|
891
|
+
---
|
|
892
|
+
|
|
893
|
+
### docs/troubleshooting.md
|
|
894
|
+
|
|
895
|
+
**目的**:常见问题与解决方案
|
|
896
|
+
|
|
897
|
+
**结构**:
|
|
125
898
|
```markdown
|
|
126
|
-
#
|
|
127
|
-
|
|
128
|
-
|
|
899
|
+
# Troubleshooting Guide
|
|
900
|
+
|
|
901
|
+
## Installation Issues
|
|
902
|
+
|
|
903
|
+
### Problem: npm install fails with EACCES error
|
|
904
|
+
|
|
905
|
+
**Symptoms**:
|
|
906
|
+
```
|
|
907
|
+
Error: EACCES: permission denied
|
|
129
908
|
```
|
|
130
909
|
|
|
131
|
-
|
|
910
|
+
**Solution**:
|
|
911
|
+
```bash
|
|
912
|
+
sudo chown -R $(whoami) ~/.npm
|
|
913
|
+
npm install
|
|
914
|
+
```
|
|
132
915
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
916
|
+
---
|
|
917
|
+
|
|
918
|
+
## Runtime Issues
|
|
919
|
+
|
|
920
|
+
### Problem: Application crashes with "Cannot find module"
|
|
921
|
+
|
|
922
|
+
**Symptoms**:
|
|
923
|
+
- Error: Cannot find module 'express'
|
|
924
|
+
- Application exits immediately
|
|
925
|
+
|
|
926
|
+
**Solution**:
|
|
927
|
+
1. Check node_modules exists
|
|
928
|
+
2. Run `npm install`
|
|
929
|
+
3. Verify package.json dependencies
|
|
930
|
+
|
|
931
|
+
**Prevention**:
|
|
932
|
+
- Always run `npm install` after pulling changes
|
|
933
|
+
- Commit package-lock.json to version control
|
|
934
|
+
```
|
|
935
|
+
|
|
936
|
+
---
|
|
937
|
+
|
|
938
|
+
## 图表文档
|
|
939
|
+
|
|
940
|
+
### 流程与图表的分离
|
|
941
|
+
|
|
942
|
+
了解 `flows/` 与 `diagrams/` 目录之间的区别:
|
|
943
|
+
|
|
944
|
+
- **`docs/diagrams/`**:静态架构图(DFD、ER、C4 模型、部署图、类图)
|
|
945
|
+
- **`docs/flows/`**:动态流程文档(时序图、API 调用流程、作业调度流程)
|
|
946
|
+
|
|
947
|
+
| 类型 | 描述 | 目录 | 示例 |
|
|
948
|
+
|------|-------------|-----------|----------|
|
|
949
|
+
| **Flow** | 动态行为:数据如何流动、步骤顺序 | `docs/flows/` | 时序图、API 调用流程、作业调度 |
|
|
950
|
+
| **Diagram** | 静态结构:系统组成、关系、数据模型 | `docs/diagrams/` | DFD、ER 图、C4 架构、部署图 |
|
|
951
|
+
|
|
952
|
+
**理由**:
|
|
953
|
+
- 清晰的分离可减少对新文档应存放在何处的困惑
|
|
954
|
+
- 静态图表极少变动;动态流程可能随功能变更而更新
|
|
955
|
+
- 目标受众不同:图表面向架构师,流程面向开发人员和运维人员
|
|
956
|
+
|
|
957
|
+
### 推荐工具
|
|
958
|
+
|
|
959
|
+
- **Mermaid**:基于文本的图表(GitHub/GitLab 原生支持)
|
|
960
|
+
- **PlantUML**:从文本生成 UML 图
|
|
961
|
+
- **Draw.io / Excalidraw**:可视化图表编辑器
|
|
962
|
+
- **ASCII Art**:简易文本图表
|
|
963
|
+
|
|
964
|
+
### Mermaid 示例
|
|
965
|
+
|
|
966
|
+
**系统流程**:
|
|
967
|
+
```mermaid
|
|
968
|
+
graph LR
|
|
969
|
+
A[User] --> B[API Gateway]
|
|
970
|
+
B --> C[Auth Service]
|
|
971
|
+
B --> D[Business Logic]
|
|
972
|
+
D --> E[Database]
|
|
136
973
|
```
|
|
137
|
-
````
|
|
138
974
|
|
|
139
|
-
|
|
975
|
+
**时序图**:
|
|
976
|
+
```mermaid
|
|
977
|
+
sequenceDiagram
|
|
978
|
+
User->>+API: POST /login
|
|
979
|
+
API->>+Auth: Validate credentials
|
|
980
|
+
Auth->>+DB: Query user
|
|
981
|
+
DB-->>-Auth: User data
|
|
982
|
+
Auth-->>-API: Token
|
|
983
|
+
API-->>-User: 200 OK + Token
|
|
984
|
+
```
|
|
985
|
+
|
|
986
|
+
### DFD(数据流图)标准
|
|
987
|
+
|
|
988
|
+
流程文档应包含 DFD 图:
|
|
989
|
+
|
|
990
|
+
| DFD 层级 | 描述 | 必需 |
|
|
991
|
+
|-----------|-------------|:--------:|
|
|
992
|
+
| 上下文图(Context Diagram) | 系统与外部实体关系 | ✅ |
|
|
993
|
+
| 0 层 DFD(Level 0 DFD) | 主要过程与数据存储 | ✅ |
|
|
994
|
+
| 1 层 DFD(Level 1 DFD) | 展开的子过程 | ⚪(视复杂度而定) |
|
|
995
|
+
| 物理 DFD(Physical DFD) | 实现映射(技术栈、数据库表、API 端点) | ⚪(高级) |
|
|
996
|
+
|
|
997
|
+
**逻辑 DFD 与物理 DFD**:
|
|
998
|
+
|
|
999
|
+
| 类型 | 描述内容 | 目标受众 | 示例内容 |
|
|
1000
|
+
|------|-----------|----------|-----------------|
|
|
1001
|
+
| **逻辑 DFD**(0/1 层) | 系统做什么(业务过程) | 业务分析师、PM、新开发人员 | 过程名称、数据流、业务规则 |
|
|
1002
|
+
| **物理 DFD** | 如何实现(技术细节) | 运维工程师、DBA、系统集成人员 | 数据库表、API 端点、文件路径、配置参数 |
|
|
1003
|
+
|
|
1004
|
+
**DFD 符号标准 (Mermaid)**:
|
|
1005
|
+
|
|
1006
|
+
| 符号 | 代表含义 | Mermaid 语法 |
|
|
1007
|
+
|--------|------------|----------------|
|
|
1008
|
+
| 矩形 | 外部实体 | `[Name]` |
|
|
1009
|
+
| 双圆 | 过程 | `((ID<br/>Name))` |
|
|
1010
|
+
| 圆柱体 | 数据存储 | `[(D# Name)]` |
|
|
1011
|
+
| 实线箭头 | 数据流 | `-->|label|` |
|
|
1012
|
+
| 虚线箭头 | 错误/异常 | `-.->|label|` |
|
|
1013
|
+
|
|
1014
|
+
**DFD 颜色标准**:
|
|
1015
|
+
|
|
1016
|
+
| 颜色 | 用途 | Mermaid 样式 |
|
|
1017
|
+
|-------|-------|---------------|
|
|
1018
|
+
| 🟦 蓝色 | 外部实体 | `fill:#e3f2fd,stroke:#1976d2` |
|
|
1019
|
+
| 🟩 绿色 | 主数据表 | `fill:#c8e6c9,stroke:#388e3c` |
|
|
1020
|
+
| 🟨 黄色 | 缓存/追踪数据 | `fill:#fff9c4,stroke:#f9a825` |
|
|
1021
|
+
| 🟧 橙色 | 已更新数据 | `fill:#ffccbc,stroke:#e64a19` |
|
|
1022
|
+
|
|
1023
|
+
---
|
|
1024
|
+
|
|
1025
|
+
## 代码示例 (`examples/`)
|
|
1026
|
+
|
|
1027
|
+
### 结构
|
|
1028
|
+
|
|
1029
|
+
```
|
|
1030
|
+
examples/
|
|
1031
|
+
├── README.md # Overview of examples
|
|
1032
|
+
├── basic-usage/
|
|
1033
|
+
│ ├── simple-auth.js # Simple authentication example
|
|
1034
|
+
│ ├── README.md # Explanation
|
|
1035
|
+
│ └── package.json # Dependencies
|
|
1036
|
+
├── advanced-usage/
|
|
1037
|
+
│ ├── custom-auth.js # Advanced authentication
|
|
1038
|
+
│ ├── README.md
|
|
1039
|
+
│ └── package.json
|
|
1040
|
+
└── integration-tests/
|
|
1041
|
+
└── ...
|
|
1042
|
+
```
|
|
1043
|
+
|
|
1044
|
+
### 示例 README 模板
|
|
140
1045
|
|
|
141
1046
|
```markdown
|
|
142
|
-
|
|
143
|
-
|
|
1047
|
+
# Basic Usage Examples
|
|
1048
|
+
|
|
1049
|
+
## Simple Authentication
|
|
1050
|
+
|
|
1051
|
+
Demonstrates basic user authentication flow.
|
|
1052
|
+
|
|
1053
|
+
### Prerequisites
|
|
1054
|
+
|
|
1055
|
+
- Node.js 18+
|
|
1056
|
+
- npm 9+
|
|
1057
|
+
|
|
1058
|
+
### Setup
|
|
1059
|
+
|
|
1060
|
+
```bash
|
|
1061
|
+
cd examples/basic-usage
|
|
1062
|
+
npm install
|
|
1063
|
+
```
|
|
1064
|
+
|
|
1065
|
+
### Run
|
|
1066
|
+
|
|
1067
|
+
```bash
|
|
1068
|
+
node simple-auth.js
|
|
1069
|
+
```
|
|
1070
|
+
|
|
1071
|
+
### Expected Output
|
|
1072
|
+
|
|
1073
|
+
```
|
|
1074
|
+
User authenticated successfully!
|
|
1075
|
+
Token: eyJhbGc...
|
|
1076
|
+
```
|
|
1077
|
+
|
|
1078
|
+
### Code Walkthrough
|
|
1079
|
+
|
|
1080
|
+
```javascript
|
|
1081
|
+
// 1. Import library
|
|
1082
|
+
const { AuthClient } = require('your-lib');
|
|
1083
|
+
|
|
1084
|
+
// 2. Create client
|
|
1085
|
+
const client = new AuthClient({
|
|
1086
|
+
apiUrl: 'https://api.example.com'
|
|
1087
|
+
});
|
|
1088
|
+
|
|
1089
|
+
// 3. Authenticate
|
|
1090
|
+
const token = await client.authenticate('user', 'pass');
|
|
1091
|
+
console.log('Token:', token);
|
|
1092
|
+
```
|
|
144
1093
|
```
|
|
145
1094
|
|
|
146
1095
|
---
|
|
147
1096
|
|
|
148
|
-
##
|
|
1097
|
+
## 文档维护
|
|
149
1098
|
|
|
150
|
-
###
|
|
1099
|
+
### 文档更新检查清单
|
|
151
1100
|
|
|
152
|
-
|
|
153
|
-
|------|-------|
|
|
154
|
-
| README.md | 必要 |
|
|
155
|
-
| LICENSE | 必要 |
|
|
156
|
-
| CHANGELOG.md | 推荐 |
|
|
157
|
-
| CONTRIBUTING.md | 推荐 |
|
|
1101
|
+
进行代码变更时,请更新文档:
|
|
158
1102
|
|
|
159
|
-
|
|
1103
|
+
- [ ] **README.md**(若符合以下情况):
|
|
1104
|
+
- 安装流程发生变更
|
|
1105
|
+
- 快速入门示例发生变更
|
|
1106
|
+
- 新增主要功能
|
|
160
1107
|
|
|
161
|
-
- [ ]
|
|
162
|
-
-
|
|
163
|
-
-
|
|
164
|
-
-
|
|
1108
|
+
- [ ] **API Reference**(若符合以下情况):
|
|
1109
|
+
- API 端点新增/变更/移除
|
|
1110
|
+
- 请求/响应格式发生变更
|
|
1111
|
+
- 引入了新的错误码
|
|
1112
|
+
|
|
1113
|
+
- [ ] **Architecture Docs**(若符合以下情况):
|
|
1114
|
+
- 系统设计发生变更
|
|
1115
|
+
- 新增组件
|
|
1116
|
+
- 技术栈发生变更
|
|
1117
|
+
|
|
1118
|
+
- [ ] **Flow Documentation**(若符合以下情况):
|
|
1119
|
+
- 业务逻辑发生变更
|
|
1120
|
+
- 新增集成
|
|
1121
|
+
- 数据流发生修改
|
|
1122
|
+
|
|
1123
|
+
- [ ] **CHANGELOG.md**(始终需要):
|
|
1124
|
+
- 为每个版本添加条目
|
|
1125
|
+
- 记录破坏性变更
|
|
1126
|
+
- 列出新功能与修复
|
|
1127
|
+
- **记录文档的新增/变更**
|
|
1128
|
+
|
|
1129
|
+
- [ ] **Cross-References**:
|
|
1130
|
+
- 更新相关文档的引用部分
|
|
1131
|
+
- 若新增文档,更新 index.md
|
|
165
1132
|
|
|
166
1133
|
---
|
|
167
1134
|
|
|
168
|
-
##
|
|
1135
|
+
## 文档质量标准
|
|
169
1136
|
|
|
170
|
-
###
|
|
1137
|
+
### 可读性
|
|
171
1138
|
|
|
172
|
-
|
|
1139
|
+
- [ ] 语言清晰、简明
|
|
1140
|
+
- [ ] 段落简短(≤5 句话)
|
|
1141
|
+
- [ ] 优先使用主动语态
|
|
1142
|
+
- [ ] 技术术语有解释
|
|
173
1143
|
|
|
174
|
-
|
|
175
|
-
|------|------|------|
|
|
176
|
-
| **规格** | 定义要建什么及如何建 | `docs/specs/` |
|
|
177
|
-
| **文档** | 说明建了什么 | `docs/` |
|
|
1144
|
+
### 准确性
|
|
178
1145
|
|
|
179
|
-
|
|
1146
|
+
- [ ] 代码示例经过测试且正常运行
|
|
1147
|
+
- [ ] 屏幕截图/图表保持最新
|
|
1148
|
+
- [ ] 版本号正确
|
|
1149
|
+
- [ ] 链接无失效
|
|
1150
|
+
|
|
1151
|
+
### 完整性
|
|
1152
|
+
|
|
1153
|
+
- [ ] 列出先决条件
|
|
1154
|
+
- [ ] 记录所有步骤
|
|
1155
|
+
- [ ] 描述预期结果
|
|
1156
|
+
- [ ] 包含疑难排解
|
|
1157
|
+
|
|
1158
|
+
### 交叉引用
|
|
1159
|
+
|
|
1160
|
+
- [ ] 链接到相关文档
|
|
1161
|
+
- [ ] 索引已更新
|
|
1162
|
+
- [ ] 参考资料部分完整
|
|
1163
|
+
|
|
1164
|
+
---
|
|
1165
|
+
|
|
1166
|
+
## 本地化
|
|
1167
|
+
|
|
1168
|
+
### 双语文档
|
|
1169
|
+
|
|
1170
|
+
对于国际化项目:
|
|
180
1171
|
|
|
181
1172
|
```
|
|
182
|
-
docs/
|
|
183
|
-
├──
|
|
184
|
-
├──
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
1173
|
+
docs/
|
|
1174
|
+
├── en/ # English documentation
|
|
1175
|
+
│ ├── README.md
|
|
1176
|
+
│ ├── getting-started.md
|
|
1177
|
+
│ └── ...
|
|
1178
|
+
├── zh-tw/ # Traditional Chinese
|
|
1179
|
+
│ ├── README.md
|
|
1180
|
+
│ ├── getting-started.md
|
|
1181
|
+
│ └── ...
|
|
1182
|
+
└── README.md # Language selector
|
|
1183
|
+
```
|
|
1184
|
+
|
|
1185
|
+
**语言选择器(根目录 docs/README.md)**:
|
|
1186
|
+
```markdown
|
|
1187
|
+
# Documentation
|
|
1188
|
+
|
|
1189
|
+
Select your language:
|
|
1190
|
+
- [English](en/README.md)
|
|
1191
|
+
- [繁體中文](zh-tw/README.md)
|
|
1192
|
+
- [日本語](ja/README.md)
|
|
1193
|
+
```
|
|
1194
|
+
|
|
1195
|
+
---
|
|
1196
|
+
|
|
1197
|
+
## 文档自动化
|
|
1198
|
+
|
|
1199
|
+
### API 文档生成
|
|
1200
|
+
|
|
1201
|
+
**工具**:
|
|
1202
|
+
- **Swagger/OpenAPI**:REST API 文档
|
|
1203
|
+
- **GraphQL**:自动生成的模式文档
|
|
1204
|
+
- **JSDoc**:JavaScript API 文档
|
|
1205
|
+
- **Doxygen**:C/C++ 文档
|
|
1206
|
+
- **Sphinx**:Python 文档
|
|
1207
|
+
- **Docusaurus**:完整文档站点
|
|
1208
|
+
|
|
1209
|
+
### 示例:Swagger 集成
|
|
1210
|
+
|
|
1211
|
+
```yaml
|
|
1212
|
+
# openapi.yaml
|
|
1213
|
+
openapi: 3.0.0
|
|
1214
|
+
info:
|
|
1215
|
+
title: User API
|
|
1216
|
+
version: 1.0.0
|
|
1217
|
+
|
|
1218
|
+
paths:
|
|
1219
|
+
/users/authenticate:
|
|
1220
|
+
post:
|
|
1221
|
+
summary: Authenticate user
|
|
1222
|
+
requestBody:
|
|
1223
|
+
required: true
|
|
1224
|
+
content:
|
|
1225
|
+
application/json:
|
|
1226
|
+
schema:
|
|
1227
|
+
type: object
|
|
1228
|
+
properties:
|
|
1229
|
+
username:
|
|
1230
|
+
type: string
|
|
1231
|
+
password:
|
|
1232
|
+
type: string
|
|
1233
|
+
responses:
|
|
1234
|
+
'200':
|
|
1235
|
+
description: Success
|
|
1236
|
+
content:
|
|
1237
|
+
application/json:
|
|
1238
|
+
schema:
|
|
1239
|
+
type: object
|
|
1240
|
+
properties:
|
|
1241
|
+
accessToken:
|
|
1242
|
+
type: string
|
|
1243
|
+
```
|
|
1244
|
+
|
|
1245
|
+
---
|
|
1246
|
+
|
|
1247
|
+
## 文档托管
|
|
1248
|
+
|
|
1249
|
+
### 选项
|
|
1250
|
+
|
|
1251
|
+
| 平台 | 最适合 | 成本 |
|
|
1252
|
+
|------|--------|------|
|
|
1253
|
+
| **GitHub Pages** | 开源项目 | 免费 |
|
|
1254
|
+
| **GitLab Pages** | GitLab 项目 | 免费 |
|
|
1255
|
+
| **Read the Docs** | Python 项目 | 免费 |
|
|
1256
|
+
| **Docusaurus** | 完整文档站点 | 免费(自托管) |
|
|
1257
|
+
| **GitBook** | 美观的文档 UI | 提供免费层级 |
|
|
1258
|
+
|
|
1259
|
+
### GitHub Pages 设置
|
|
1260
|
+
|
|
1261
|
+
```bash
|
|
1262
|
+
# 1. Create docs branch
|
|
1263
|
+
git checkout --orphan gh-pages
|
|
1264
|
+
|
|
1265
|
+
# 2. Add documentation
|
|
1266
|
+
cp -r docs/* .
|
|
1267
|
+
|
|
1268
|
+
# 3. Push to GitHub
|
|
1269
|
+
git add .
|
|
1270
|
+
git commit -m "docs: initial documentation"
|
|
1271
|
+
git push origin gh-pages
|
|
1272
|
+
|
|
1273
|
+
# 4. Enable in GitHub Settings → Pages
|
|
1274
|
+
# Choose gh-pages branch
|
|
188
1275
|
```
|
|
189
1276
|
|
|
190
1277
|
---
|
|
191
1278
|
|
|
192
1279
|
## 开发中间产物(工作文件)
|
|
193
1280
|
|
|
194
|
-
|
|
1281
|
+
开发过程会产生不属于正式文档但需要可被发现的中间文件。这些“工作文件”存放在 `docs/working/` 中,并有定义的生命周期。
|
|
195
1282
|
|
|
196
1283
|
### 目录结构
|
|
197
1284
|
|
|
198
1285
|
```
|
|
199
1286
|
docs/working/
|
|
200
|
-
├── README.md #
|
|
1287
|
+
├── README.md # Index and lifecycle rules
|
|
201
1288
|
├── brainstorms/ # YYYY-MM-DD-topic.md
|
|
202
|
-
├── investigations/ #
|
|
1289
|
+
├── investigations/ # Technical investigations and research
|
|
203
1290
|
├── rfcs/ # RFC-NNN-title.md
|
|
204
|
-
├── meeting-notes/ #
|
|
205
|
-
└── poc/ #
|
|
1291
|
+
├── meeting-notes/ # Meeting records
|
|
1292
|
+
└── poc/ # Proof of concept documents
|
|
206
1293
|
└── {poc-name}/
|
|
207
|
-
└── README.md #
|
|
1294
|
+
└── README.md # Findings, conclusions, next steps
|
|
208
1295
|
```
|
|
209
1296
|
|
|
210
1297
|
### 状态头部(必需)
|
|
@@ -215,8 +1302,8 @@ docs/working/
|
|
|
215
1302
|
---
|
|
216
1303
|
status: draft | active | graduated | archived
|
|
217
1304
|
created: YYYY-MM-DD
|
|
218
|
-
author:
|
|
219
|
-
graduated-to: path/to/formal-doc.md #
|
|
1305
|
+
author: name
|
|
1306
|
+
graduated-to: path/to/formal-doc.md # if graduated
|
|
220
1307
|
---
|
|
221
1308
|
```
|
|
222
1309
|
|
|
@@ -249,36 +1336,36 @@ graduated-to: path/to/formal-doc.md # 若已毕业
|
|
|
249
1336
|
|
|
250
1337
|
---
|
|
251
1338
|
|
|
252
|
-
##
|
|
1339
|
+
## 扩展文档类型矩阵
|
|
253
1340
|
|
|
254
|
-
|
|
1341
|
+
本矩阵扩展上方的文档需求矩阵,包含所有文档类型及其标准位置。
|
|
255
1342
|
|
|
256
|
-
###
|
|
1343
|
+
### 代码相关文档
|
|
257
1344
|
|
|
258
1345
|
| 文件类型 | 位置 | 说明 |
|
|
259
|
-
|
|
1346
|
+
|-----------|----------|-------|
|
|
260
1347
|
| API 参考 | `docs/api-reference.md` | 建议自动生成 |
|
|
261
1348
|
| 架构概览 | `docs/architecture.md` | 高级系统设计 |
|
|
262
1349
|
| ADR | `docs/ADR/NNN-title.md` | 架构决策记录 |
|
|
263
|
-
| 规格 | `docs/specs/` |
|
|
1350
|
+
| 规格 | `docs/specs/` | 规格文档 |
|
|
264
1351
|
| 疑难排解 | `docs/troubleshooting.md` | 常见问题与解决方案 |
|
|
265
1352
|
| 流程图 | `docs/flows/` | 流程与数据流 |
|
|
266
1353
|
| 架构图 | `docs/diagrams/` | 可视化架构(.mmd、.puml) |
|
|
267
1354
|
|
|
268
|
-
###
|
|
1355
|
+
### 工作文档
|
|
269
1356
|
|
|
270
1357
|
| 文件类型 | 位置 | 说明 |
|
|
271
|
-
|
|
1358
|
+
|-----------|----------|-------|
|
|
272
1359
|
| 头脑风暴 | `docs/working/brainstorms/` | 日期前缀、生命周期管理 |
|
|
273
1360
|
| 技术调查 | `docs/working/investigations/` | 技术研究报告 |
|
|
274
|
-
| RFC | `docs/working/rfcs/` |
|
|
1361
|
+
| RFC | `docs/working/rfcs/` | 意见征求稿,编号管理 |
|
|
275
1362
|
| 会议记录 | `docs/working/meeting-notes/` | 日期前缀记录 |
|
|
276
1363
|
| POC 报告 | `docs/working/poc/` | 每个 POC 一个子目录 |
|
|
277
1364
|
|
|
278
|
-
###
|
|
1365
|
+
### 项目级别文档
|
|
279
1366
|
|
|
280
1367
|
| 文件类型 | 位置 | 说明 |
|
|
281
|
-
|
|
1368
|
+
|-----------|----------|-------|
|
|
282
1369
|
| README | 根目录 `/` | 大写,必需 |
|
|
283
1370
|
| CONTRIBUTING | 根目录 `/` | 大写 |
|
|
284
1371
|
| CHANGELOG | 根目录 `/` | 大写,Keep a Changelog 格式 |
|
|
@@ -289,10 +1376,67 @@ graduated-to: path/to/formal-doc.md # 若已毕业
|
|
|
289
1376
|
|
|
290
1377
|
---
|
|
291
1378
|
|
|
1379
|
+
## 文档测试
|
|
1380
|
+
|
|
1381
|
+
文档应当进行系统化测试,而不仅是人工审查。本节定义了可测试的质量层。
|
|
1382
|
+
|
|
1383
|
+
### 测试层
|
|
1384
|
+
|
|
1385
|
+
| 层级 | 测试内容 | 工具 | CI 阶段 |
|
|
1386
|
+
|-------|---------------|-------|----------|
|
|
1387
|
+
| **链接验证** | 所有内部/外部链接可解析 | markdown-link-check, lychee | Pre-commit / PR |
|
|
1388
|
+
| **代码示例测试** | 代码示例能够编译并运行 | doctest, mdx-js, 自定义脚本 | PR 检查 |
|
|
1389
|
+
| **结构验证** | 必需章节存在,标题层级正确 | 自定义 linter, remark-lint | Pre-commit |
|
|
1390
|
+
| **内容新鲜度** | 文档在保留期限内更新 | 自定义脚本(检查最后更新日期) | 发布 |
|
|
1391
|
+
| **可追溯性** | 每个功能都有文档,每份文档都映射到代码 | 追溯矩阵 | 发布 |
|
|
1392
|
+
|
|
1393
|
+
### 代码示例验证
|
|
1394
|
+
|
|
1395
|
+
文档中的代码示例应予以验证,以防止偏离实际实现:
|
|
1396
|
+
|
|
1397
|
+
```markdown
|
|
1398
|
+
<!-- doctest: lang=bash, skip=false -->
|
|
1399
|
+
```bash
|
|
1400
|
+
npm install your-package
|
|
1401
|
+
npm test
|
|
1402
|
+
```
|
|
1403
|
+
```
|
|
1404
|
+
|
|
1405
|
+
**验证方法**:
|
|
1406
|
+
|
|
1407
|
+
| 方法 | 描述 | 最适合 |
|
|
1408
|
+
|----------|-------------|----------|
|
|
1409
|
+
| **提取并运行** | 提取代码块,在沙箱中执行 | CLI 示例、脚本 |
|
|
1410
|
+
| **从源导入** | 在文档中包含实际源文件 | API 使用示例 |
|
|
1411
|
+
| **快照比对** | 将输出与预期进行比对 | 命令输出示例 |
|
|
1412
|
+
|
|
1413
|
+
### 文档追溯矩阵
|
|
1414
|
+
|
|
1415
|
+
追踪功能、代码与文档之间的关系:
|
|
1416
|
+
|
|
1417
|
+
```markdown
|
|
1418
|
+
| Feature | Code Location | Documentation | Test | Status |
|
|
1419
|
+
|---------|---------------|---------------|------|--------|
|
|
1420
|
+
| User auth | src/auth/ | docs/api.md#auth | tests/auth.test.js | ✅ Current |
|
|
1421
|
+
| Export CSV | src/export/ | docs/api.md#export | tests/export.test.js | ⚠️ Stale |
|
|
1422
|
+
| Webhooks | src/webhooks/ | ❌ Missing | tests/webhooks.test.js | ❌ Undocumented |
|
|
1423
|
+
```
|
|
1424
|
+
|
|
1425
|
+
### CI/CD 集成
|
|
1426
|
+
|
|
1427
|
+
| 阶段 | 检查项 | 阻断 |
|
|
1428
|
+
|-------|--------|:--------:|
|
|
1429
|
+
| **Pre-commit** | 链接检查、结构 lint | ✅ 是 |
|
|
1430
|
+
| **PR 检查** | 代码示例验证、新鲜度 | ✅ 是 |
|
|
1431
|
+
| **发布** | 完整可追溯性审计、所有层级 | ⚠️ 警告 |
|
|
1432
|
+
|
|
1433
|
+
---
|
|
1434
|
+
|
|
292
1435
|
## 相关标准
|
|
293
1436
|
|
|
294
|
-
- [
|
|
1437
|
+
- [文档编写标准](documentation-writing-standards.md)
|
|
295
1438
|
- [变更日志标准](changelog-standards.md)
|
|
1439
|
+
- [项目结构标准](project-structure.md)
|
|
296
1440
|
- [规格驱动开发](spec-driven-development.md)
|
|
297
1441
|
|
|
298
1442
|
---
|
|
@@ -300,13 +1444,26 @@ graduated-to: path/to/formal-doc.md # 若已毕业
|
|
|
300
1444
|
## 版本历史
|
|
301
1445
|
|
|
302
1446
|
| 版本 | 日期 | 变更 |
|
|
303
|
-
|
|
304
|
-
| 1.
|
|
305
|
-
| 1.
|
|
306
|
-
| 1.
|
|
1447
|
+
|---------|------|---------|
|
|
1448
|
+
| 1.5.0 | 2026-03-17 | 新增:Diátaxis 文档分类、LLM 发现文件(llms.txt)、文档测试标准(5 层测试、追溯矩阵、CI/CD 集成) |
|
|
1449
|
+
| 1.4.0 | 2026-03-04 | 新增:开发中间产物(docs/working/)目录与生命周期管理、扩展文档类型矩阵 |
|
|
1450
|
+
| 1.3.0 | 2026-01-24 | 新增:带 specs/ 目录结构的规格文档标准 |
|
|
1451
|
+
| 1.2.2 | 2025-12-24 | 新增:相关标准章节 |
|
|
1452
|
+
| 1.2.1 | 2025-12-12 | 新增:物理 DFD 层、流程与架构图分离说明 |
|
|
1453
|
+
| 1.2.0 | 2025-12-11 | 新增:流程文档标准、交叉引用标准、索引文档标准、CHANGELOG 文档集成、文档需求矩阵、DFD 标准 |
|
|
1454
|
+
| 1.1.0 | 2025-12-11 | 新增:文件命名规范、文档版本对齐标准 |
|
|
1455
|
+
| 1.0.0 | 2025-11-12 | 初始文档结构标准 |
|
|
1456
|
+
|
|
1457
|
+
---
|
|
1458
|
+
|
|
1459
|
+
## 参考资料
|
|
1460
|
+
|
|
1461
|
+
- [Write the Docs](https://www.writethedocs.org/)
|
|
1462
|
+
- [Google Developer Documentation Style Guide](https://developers.google.com/style)
|
|
1463
|
+
- [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/)
|
|
307
1464
|
|
|
308
1465
|
---
|
|
309
1466
|
|
|
310
1467
|
## 许可证
|
|
311
1468
|
|
|
312
|
-
本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
|
|
1469
|
+
本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可发布。
|