universal-dev-standards 6.14.0-beta.8 → 6.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/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/secret-management-standards.ai.yaml +12 -1
- package/bundled/core/commit-message-guide.md +22 -19
- package/bundled/core/secret-management-standards.md +13 -1
- package/bundled/extensions/locales/zh-tw.md +19 -19
- package/bundled/hooks/validate-commit-msg.mjs +52 -9
- package/bundled/locales/zh-CN/CHANGELOG.md +2312 -1102
- 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 +3 -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/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/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 +2291 -1110
- 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 +3 -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/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/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 +77 -7
- 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-split.js +2 -1
- package/src/commands/spec.js +11 -2
- package/src/commands/update.js +184 -30
- 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 +160 -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,40 +2,44 @@
|
|
|
2
2
|
source: ../../../core/documentation-writing-standards.md
|
|
3
3
|
source_version: 1.2.0
|
|
4
4
|
translation_version: 1.2.0
|
|
5
|
-
last_synced: 2026-
|
|
5
|
+
last_synced: 2026-10-16
|
|
6
|
+
source_hash: 9d2d83e23aef
|
|
6
7
|
status: current
|
|
7
8
|
---
|
|
8
9
|
|
|
9
|
-
#
|
|
10
|
+
# 文档编写规范
|
|
10
11
|
|
|
11
|
-
> [
|
|
12
|
+
> **English** | [繁体中文](../../zh-TW/core/documentation-writing-standards.md)
|
|
12
13
|
|
|
13
14
|
**版本**: 1.2.0
|
|
14
15
|
**最后更新**: 2026-03-17
|
|
15
|
-
**适用范围**:
|
|
16
|
+
**适用范围**: 所有软件项目(新建、重构、迁移、维护)
|
|
17
|
+
**范围**: partial
|
|
18
|
+
**行业标准**: OpenAPI 3.1, AsyncAPI 2.6, JSON Schema 2020-12, WCAG 2.1 (文档可及性)
|
|
19
|
+
**参考资料**: [openapis.org](https://www.openapis.org/)
|
|
16
20
|
|
|
17
21
|
---
|
|
18
22
|
|
|
19
23
|
## 目的
|
|
20
24
|
|
|
21
|
-
|
|
25
|
+
本标准根据项目类型定义文档需求,并提供各类文档的详细编写指南。
|
|
22
26
|
|
|
23
27
|
**与其他标准的关系**:
|
|
24
|
-
- 补充 [documentation-structure.md](documentation-structure.md)
|
|
25
|
-
-
|
|
28
|
+
- 补充 [documentation-structure.md](documentation-structure.md) 所定义的文件组织
|
|
29
|
+
- 本标准聚焦于**内容需求**和**项目类型映射**
|
|
26
30
|
|
|
27
31
|
---
|
|
28
32
|
|
|
29
|
-
##
|
|
33
|
+
## 项目类型与所需文档
|
|
30
34
|
|
|
31
|
-
###
|
|
35
|
+
### 文档需求矩阵
|
|
32
36
|
|
|
33
|
-
|
|
|
37
|
+
| 文档 | 新建项目 | 重构 | 迁移 | 维护 | 说明 |
|
|
34
38
|
|----------|:-----------:|:-----------:|:---------:|:-----------:|-------------|
|
|
35
|
-
| **README.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 |
|
|
39
|
+
| **README.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 | 项目入口 |
|
|
36
40
|
| **ARCHITECTURE.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | 系统架构 |
|
|
37
|
-
| **API.md** | ⚪ 如适用 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | API
|
|
38
|
-
| **DATABASE.md** | ⚪ 如适用 | ✅ 必要 | ✅ 必要 | ⚪ 建议 |
|
|
41
|
+
| **API.md** | ⚪ 如适用 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | API 规范 |
|
|
42
|
+
| **DATABASE.md** | ⚪ 如适用 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | 数据库架构 |
|
|
39
43
|
| **DEPLOYMENT.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建议 | 部署指南 |
|
|
40
44
|
| **MIGRATION.md** | ❌ 不需要 | ✅ 必要 | ✅ 必要 | ❌ 不需要 | 迁移计划 |
|
|
41
45
|
| **ADR/** | ⚪ 建议 | ✅ 必要 | ✅ 必要 | ⚪ 如适用 | 架构决策 |
|
|
@@ -46,30 +50,30 @@ status: current
|
|
|
46
50
|
|
|
47
51
|
---
|
|
48
52
|
|
|
49
|
-
###
|
|
53
|
+
### 项目类型说明
|
|
50
54
|
|
|
51
|
-
#### 🆕
|
|
55
|
+
#### 🆕 新建项目
|
|
52
56
|
|
|
53
|
-
|
|
57
|
+
从零开始构建软件。
|
|
54
58
|
|
|
55
|
-
|
|
56
|
-
- README.md -
|
|
59
|
+
**必要文档**:
|
|
60
|
+
- README.md - 项目概述、快速开始
|
|
57
61
|
- ARCHITECTURE.md - 设计架构(开发前规划)
|
|
58
62
|
- DEPLOYMENT.md - 部署流程
|
|
59
63
|
- CHANGELOG.md - 版本历史
|
|
60
64
|
|
|
61
|
-
|
|
65
|
+
**建议文档**:
|
|
62
66
|
- API.md - 如对外提供 API
|
|
63
|
-
- DATABASE.md -
|
|
67
|
+
- DATABASE.md - 如使用数据库
|
|
64
68
|
- ADR/ - 记录重要技术决策
|
|
65
69
|
|
|
66
70
|
---
|
|
67
71
|
|
|
68
|
-
#### 🔄
|
|
72
|
+
#### 🔄 重构项目
|
|
69
73
|
|
|
70
|
-
|
|
74
|
+
在不改变外部行为的前提下,改善既有系统的代码结构、架构或技术栈。
|
|
71
75
|
|
|
72
|
-
|
|
76
|
+
**必要文档**:
|
|
73
77
|
- README.md - 更新技术栈说明
|
|
74
78
|
- ARCHITECTURE.md - 新旧架构对比
|
|
75
79
|
- API.md - API 变更说明(如适用)
|
|
@@ -80,74 +84,106 @@ status: current
|
|
|
80
84
|
- CHANGELOG.md - 详细变更记录
|
|
81
85
|
|
|
82
86
|
**重点**:
|
|
83
|
-
- MIGRATION.md
|
|
84
|
-
- ADR/
|
|
87
|
+
- MIGRATION.md 必须包含回滚计划
|
|
88
|
+
- ADR/ 必须记录“为何重构”及“为何采用此方案”
|
|
85
89
|
|
|
86
90
|
---
|
|
87
91
|
|
|
88
|
-
#### 🚚
|
|
92
|
+
#### 🚚 迁移项目
|
|
89
93
|
|
|
90
|
-
|
|
94
|
+
将系统从一个环境/平台迁移到另一个(如云迁移、版本升级)。
|
|
91
95
|
|
|
92
|
-
|
|
96
|
+
**必要文档**:
|
|
93
97
|
- README.md - 新环境说明
|
|
94
98
|
- ARCHITECTURE.md - 新架构图
|
|
95
|
-
- API.md - API
|
|
96
|
-
- DATABASE.md -
|
|
99
|
+
- API.md - API 兼容性说明
|
|
100
|
+
- DATABASE.md - 数据迁移说明
|
|
97
101
|
- DEPLOYMENT.md - 新环境部署
|
|
98
102
|
- MIGRATION.md - 迁移步骤与验证
|
|
99
103
|
- ADR/ - 迁移决策记录
|
|
100
104
|
- CHANGELOG.md - 迁移变更记录
|
|
101
105
|
|
|
102
106
|
**重点**:
|
|
103
|
-
- MIGRATION.md
|
|
104
|
-
-
|
|
107
|
+
- MIGRATION.md 是核心文档
|
|
108
|
+
- 必须包含数据迁移验证、回滚计划、集成方通知
|
|
105
109
|
|
|
106
110
|
---
|
|
107
111
|
|
|
108
|
-
#### 🔧
|
|
112
|
+
#### 🔧 维护项目
|
|
109
113
|
|
|
110
|
-
既有系统的日常维护、Bug
|
|
114
|
+
既有系统的日常维护、Bug 修复、次要功能增强。
|
|
111
115
|
|
|
112
|
-
|
|
116
|
+
**必要文档**:
|
|
113
117
|
- README.md - 保持更新
|
|
114
118
|
- CHANGELOG.md - 记录每次变更
|
|
115
119
|
|
|
116
|
-
|
|
117
|
-
-
|
|
120
|
+
**建议文档**:
|
|
121
|
+
- 依据变更范围更新其他文档
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 文档语言配置
|
|
126
|
+
|
|
127
|
+
文档语言与 [commit-message-guide.md](commit-message-guide.md) 共享 `output_language` 设置。此统一设置控制项目中所有书面输出的语言。
|
|
128
|
+
|
|
129
|
+
### 语言选项
|
|
130
|
+
|
|
131
|
+
| 设置值 | 提交信息 | 文档 |
|
|
132
|
+
|--------------|----------------|---------------|
|
|
133
|
+
| `english` | 仅英文 | 仅英文 |
|
|
134
|
+
| `traditional-chinese` | 仅繁体中文 | 仅繁体中文 |
|
|
135
|
+
| `bilingual` | 英文 + 中文 | 分层双语(见下文) |
|
|
136
|
+
|
|
137
|
+
### 文档分层(双语模式)
|
|
138
|
+
|
|
139
|
+
当 `output_language` 设置为 `bilingual` 时,文档遵循三层体系:
|
|
140
|
+
|
|
141
|
+
| 层级 | 文档 | 行为 | 理由 |
|
|
142
|
+
|------|-----------|----------|-----------|
|
|
143
|
+
| **L1 — 强制** | 提交信息、CHANGELOG.md、PR 描述 | 自动双语 | 直接由语言设置控制 |
|
|
144
|
+
| **L2 — 建议** | README.md、CONTRIBUTING.md、ADR/ | AI 建议双语 | 开发者最常阅读 |
|
|
145
|
+
| **L3 — 不受影响** | ARCHITECTURE.md、API.md、DATABASE.md、DEPLOYMENT.md、MIGRATION.md | 遵循显示语言 | 技术规范;双语会增加过多冗余 |
|
|
146
|
+
|
|
147
|
+
### 双语文档格式
|
|
148
|
+
|
|
149
|
+
使用段落级双语格式,与双语提交信息正文保持一致:
|
|
150
|
+
|
|
151
|
+
- 英文段落居前,后接空行,然后是中文段落
|
|
152
|
+
- 代码块与表格仅编写一次(不重复)
|
|
153
|
+
- 章节标题使用 `|` 分隔符:`## Installation | 安装`
|
|
118
154
|
|
|
119
155
|
---
|
|
120
156
|
|
|
121
157
|
## 核心原则
|
|
122
158
|
|
|
123
|
-
>
|
|
159
|
+
> **文档是代码的延伸,应与代码同等重视。好的文档能减少沟通成本、加速新人上手、降低维护风险。**
|
|
124
160
|
|
|
125
|
-
###
|
|
161
|
+
### 文档金字塔
|
|
126
162
|
|
|
127
163
|
```
|
|
128
164
|
┌─────────────┐
|
|
129
|
-
│ README │ ←
|
|
165
|
+
│ README │ ← Entry point, quick overview
|
|
130
166
|
├─────────────┤
|
|
131
167
|
┌──┴─────────────┴──┐
|
|
132
|
-
│ ARCHITECTURE │ ←
|
|
168
|
+
│ ARCHITECTURE │ ← System overview
|
|
133
169
|
├───────────────────┤
|
|
134
170
|
┌──┴───────────────────┴──┐
|
|
135
|
-
│ API / DATABASE / DEPLOY │ ←
|
|
171
|
+
│ API / DATABASE / DEPLOY │ ← Technical details
|
|
136
172
|
├─────────────────────────┤
|
|
137
173
|
┌──┴─────────────────────────┴──┐
|
|
138
|
-
│ ADR / MIGRATION / CHANGELOG │ ←
|
|
174
|
+
│ ADR / MIGRATION / CHANGELOG │ ← Change history
|
|
139
175
|
└───────────────────────────────┘
|
|
140
176
|
```
|
|
141
177
|
|
|
142
178
|
---
|
|
143
179
|
|
|
144
|
-
##
|
|
180
|
+
## 文档分类与规范
|
|
145
181
|
|
|
146
|
-
### 1.
|
|
182
|
+
### 1. 架构文档
|
|
147
183
|
|
|
148
184
|
#### ARCHITECTURE.md
|
|
149
185
|
|
|
150
|
-
**用途**:
|
|
186
|
+
**用途**: 描述系统整体架构、模块划分、技术选型
|
|
151
187
|
|
|
152
188
|
**必要章节**:
|
|
153
189
|
|
|
@@ -155,33 +191,33 @@ status: current
|
|
|
155
191
|
|---------|-------------|----------|
|
|
156
192
|
| 系统概述 | 目的、范围、主要功能 | 必要 |
|
|
157
193
|
| 架构图 | 使用 Mermaid 或 ASCII Art | 必要 |
|
|
158
|
-
|
|
|
159
|
-
| 技术栈 |
|
|
160
|
-
|
|
|
194
|
+
| 模块说明 | 职责、依赖关系 | 必要 |
|
|
195
|
+
| 技术栈 | 框架、语言、数据库版本 | 必要 |
|
|
196
|
+
| 数据流 | 主要业务流程数据流向 | 必要 |
|
|
161
197
|
| 部署架构 | 生产环境部署拓扑 | 建议 |
|
|
162
|
-
| 设计决策 |
|
|
198
|
+
| 设计决策 | 关键决策的理由(或链接至 ADR) | 建议 |
|
|
163
199
|
|
|
164
|
-
|
|
200
|
+
**模板结构**:
|
|
165
201
|
|
|
166
202
|
```markdown
|
|
167
203
|
# 系统架构
|
|
168
204
|
|
|
169
|
-
## 1.
|
|
170
|
-
[
|
|
205
|
+
## 1. 概述
|
|
206
|
+
[系统目的和范围]
|
|
171
207
|
|
|
172
208
|
## 2. 架构图
|
|
173
209
|
[Mermaid 或 ASCII 图]
|
|
174
210
|
|
|
175
|
-
## 3.
|
|
211
|
+
## 3. 模块说明
|
|
176
212
|
### 3.1 表现层
|
|
177
213
|
### 3.2 业务逻辑层
|
|
178
|
-
### 3.3
|
|
214
|
+
### 3.3 数据访问层
|
|
179
215
|
|
|
180
216
|
## 4. 技术栈
|
|
181
217
|
| 类别 | 技术 | 版本 |
|
|
182
218
|
|----------|------------|---------|
|
|
183
219
|
|
|
184
|
-
## 5.
|
|
220
|
+
## 5. 数据流
|
|
185
221
|
[主要业务流程图]
|
|
186
222
|
|
|
187
223
|
## 6. 部署架构
|
|
@@ -190,23 +226,23 @@ status: current
|
|
|
190
226
|
|
|
191
227
|
---
|
|
192
228
|
|
|
193
|
-
### 2. API
|
|
229
|
+
### 2. API 文档
|
|
194
230
|
|
|
195
231
|
#### API.md
|
|
196
232
|
|
|
197
|
-
**用途**:
|
|
233
|
+
**用途**: 记录外部 API 接口
|
|
198
234
|
|
|
199
235
|
**必要章节**:
|
|
200
236
|
|
|
201
237
|
| 章节 | 说明 | 必要性 |
|
|
202
238
|
|---------|-------------|----------|
|
|
203
|
-
| API 概述 |
|
|
204
|
-
| 认证方式 | Token
|
|
239
|
+
| API 概述 | 版本、基础 URL、认证方式 | 必要 |
|
|
240
|
+
| 认证方式 | Token 获取、过期时间 | 必要 |
|
|
205
241
|
| 端点列表 | 所有 API 端点 | 必要 |
|
|
206
|
-
| 端点规格 |
|
|
242
|
+
| 端点规格 | 每个端点的请求/响应格式 | 必要 |
|
|
207
243
|
| 错误码参考 | 错误码与说明 | 必要 |
|
|
208
|
-
|
|
|
209
|
-
| 速率限制 | API
|
|
244
|
+
| 代码示例 | 常见语言的代码示例 | 建议 |
|
|
245
|
+
| 速率限制 | API 调用频率限制 | 如适用 |
|
|
210
246
|
|
|
211
247
|
**端点规格格式**:
|
|
212
248
|
|
|
@@ -217,12 +253,12 @@ status: current
|
|
|
217
253
|
|
|
218
254
|
**请求**
|
|
219
255
|
|
|
220
|
-
|
|
|
256
|
+
| 字段 | 类型 | 必要 | 说明 |
|
|
221
257
|
|-------|------|----------|-------------|
|
|
222
258
|
| field1 | string | 是 | 说明 |
|
|
223
259
|
| field2 | integer | 否 | 说明 |
|
|
224
260
|
|
|
225
|
-
|
|
261
|
+
**请求示例**
|
|
226
262
|
```json
|
|
227
263
|
{
|
|
228
264
|
"field1": "value",
|
|
@@ -230,14 +266,14 @@ status: current
|
|
|
230
266
|
}
|
|
231
267
|
```
|
|
232
268
|
|
|
233
|
-
|
|
269
|
+
**响应**
|
|
234
270
|
|
|
235
|
-
|
|
|
271
|
+
| 字段 | 类型 | 说明 |
|
|
236
272
|
|-------|------|-------------|
|
|
237
273
|
| success | boolean | 是否成功 |
|
|
238
|
-
| data | object |
|
|
274
|
+
| data | object | 响应数据 |
|
|
239
275
|
|
|
240
|
-
|
|
276
|
+
**响应示例**
|
|
241
277
|
```json
|
|
242
278
|
{
|
|
243
279
|
"success": true,
|
|
@@ -245,65 +281,65 @@ status: current
|
|
|
245
281
|
}
|
|
246
282
|
```
|
|
247
283
|
|
|
248
|
-
|
|
284
|
+
**错误响应**
|
|
249
285
|
| 代码 | 说明 |
|
|
250
286
|
|------|-------------|
|
|
251
|
-
| 400 |
|
|
287
|
+
| 400 | 错误的请求 |
|
|
252
288
|
| 401 | 未授权 |
|
|
253
289
|
```
|
|
254
290
|
|
|
255
291
|
---
|
|
256
292
|
|
|
257
|
-
### 3.
|
|
293
|
+
### 3. 数据库文档
|
|
258
294
|
|
|
259
295
|
#### DATABASE.md
|
|
260
296
|
|
|
261
|
-
**用途**:
|
|
297
|
+
**用途**: 记录数据库结构、关联关系、索引策略
|
|
262
298
|
|
|
263
299
|
**必要章节**:
|
|
264
300
|
|
|
265
301
|
| 章节 | 说明 | 必要性 |
|
|
266
302
|
|---------|-------------|----------|
|
|
267
|
-
|
|
|
268
|
-
| ER 图 |
|
|
269
|
-
|
|
|
270
|
-
|
|
|
271
|
-
| 索引说明 |
|
|
303
|
+
| 数据库概述 | 类型、版本、连接信息 | 必要 |
|
|
304
|
+
| ER 图 | 实体关系图 | 必要 |
|
|
305
|
+
| 数据表列表 | 所有数据表及用途 | 必要 |
|
|
306
|
+
| 数据表规格 | 每个数据表的列定义 | 必要 |
|
|
307
|
+
| 索引说明 | 索引策略与性能考量 | 必要 |
|
|
272
308
|
| 迁移脚本 | 脚本位置与执行顺序 | 必要 |
|
|
273
309
|
| 备份策略 | 备份频率、保留期限 | 建议 |
|
|
274
310
|
|
|
275
|
-
|
|
311
|
+
**数据表规格格式**:
|
|
276
312
|
|
|
277
313
|
```markdown
|
|
278
|
-
###
|
|
314
|
+
### TableName
|
|
279
315
|
|
|
280
|
-
|
|
316
|
+
数据表用途说明。
|
|
281
317
|
|
|
282
|
-
|
|
318
|
+
**列定义**
|
|
283
319
|
|
|
284
|
-
|
|
|
320
|
+
| 列 | 数据类型 | 可空 | 默认值 | 说明 |
|
|
285
321
|
|--------|-----------|----------|---------|-------------|
|
|
286
322
|
| id | bigint | 否 | IDENTITY | 主键 |
|
|
287
|
-
| name | varchar(100) | 否 | - |
|
|
288
|
-
| status | tinyint | 否 | 0 |
|
|
323
|
+
| name | varchar(100) | 否 | - | 名称字段 |
|
|
324
|
+
| status | tinyint | 否 | 0 | 状态标志 |
|
|
289
325
|
|
|
290
326
|
**索引**
|
|
291
327
|
|
|
292
|
-
| 索引名称 |
|
|
328
|
+
| 索引名称 | 列 | 类型 | 说明 |
|
|
293
329
|
|------------|---------|------|-------------|
|
|
294
330
|
| PK_TableName | id | CLUSTERED | 主键 |
|
|
295
|
-
| IX_Status | status, created_at | NONCLUSTERED |
|
|
331
|
+
| IX_Status | status, created_at | NONCLUSTERED | 查询优化 |
|
|
296
332
|
|
|
297
|
-
|
|
333
|
+
**关系**
|
|
298
334
|
|
|
299
|
-
|
|
|
335
|
+
| 关联表 | 连接列 | 关系 |
|
|
300
336
|
|---------------|--------------|--------------|
|
|
301
337
|
| OtherTable | id = other_id | 1:N |
|
|
302
338
|
```
|
|
303
339
|
|
|
304
340
|
---
|
|
305
341
|
|
|
306
|
-
### 4.
|
|
342
|
+
### 4. 部署文档
|
|
307
343
|
|
|
308
344
|
#### DEPLOYMENT.md
|
|
309
345
|
|
|
@@ -313,45 +349,45 @@ status: current
|
|
|
313
349
|
|
|
314
350
|
| 章节 | 说明 | 必要性 |
|
|
315
351
|
|---------|-------------|----------|
|
|
316
|
-
|
|
|
352
|
+
| 环境要求 | 硬件、软件、网络要求 | 必要 |
|
|
317
353
|
| 安装步骤 | 详细安装流程 | 必要 |
|
|
318
|
-
| 配置说明 |
|
|
354
|
+
| 配置说明 | 配置文件参数 | 必要 |
|
|
319
355
|
| 验证方式 | 如何确认部署成功 | 必要 |
|
|
320
|
-
| 故障排除 |
|
|
321
|
-
|
|
|
322
|
-
| 扩展指南 |
|
|
356
|
+
| 故障排除 | 常见问题与解决方案 | 必要 |
|
|
357
|
+
| 监控 | 健康检查、日志位置 | 建议 |
|
|
358
|
+
| 扩展指南 | 如何进行水平/垂直扩展 | 如适用 |
|
|
323
359
|
|
|
324
|
-
|
|
360
|
+
**配置文档格式**:
|
|
325
361
|
|
|
326
362
|
```markdown
|
|
327
|
-
### config.yaml
|
|
363
|
+
### config.yaml 设置
|
|
328
364
|
|
|
329
|
-
| 参数 |
|
|
365
|
+
| 参数 | 默认值 | 说明 | 示例 |
|
|
330
366
|
|-----------|---------|-------------|---------|
|
|
331
|
-
| db.host | localhost |
|
|
332
|
-
| db.port | 5432 |
|
|
333
|
-
| app.timeout | 300 |
|
|
367
|
+
| db.host | localhost | 数据库主机 | `192.168.1.100` |
|
|
368
|
+
| db.port | 5432 | 数据库端口 | - |
|
|
369
|
+
| app.timeout | 300 | 请求超时(秒) | - |
|
|
334
370
|
```
|
|
335
371
|
|
|
336
372
|
---
|
|
337
373
|
|
|
338
|
-
### 5.
|
|
374
|
+
### 5. 迁移文档
|
|
339
375
|
|
|
340
376
|
#### MIGRATION.md
|
|
341
377
|
|
|
342
|
-
**用途**:
|
|
378
|
+
**用途**: 记录迁移计划、向后兼容策略、回滚程序
|
|
343
379
|
|
|
344
380
|
**必要章节**:
|
|
345
381
|
|
|
346
382
|
| 章节 | 说明 | 必要性 |
|
|
347
383
|
|---------|-------------|----------|
|
|
348
|
-
| 迁移概述 |
|
|
349
|
-
|
|
|
384
|
+
| 迁移概述 | 目标、范围、时间表 | 必要 |
|
|
385
|
+
| 前提条件 | 迁移前所需的准备工作 | 必要 |
|
|
350
386
|
| 迁移步骤 | 详细迁移流程 | 必要 |
|
|
351
387
|
| 验证清单 | 迁移后验证项目 | 必要 |
|
|
352
388
|
| 回滚计划 | 失败时的回滚步骤 | 必要 |
|
|
353
|
-
|
|
|
354
|
-
| 集成方通知 |
|
|
389
|
+
| 向后兼容性 | API/数据库兼容性说明 | 必要 |
|
|
390
|
+
| 集成方通知 | 需要通知的外部系统 | 如适用 |
|
|
355
391
|
|
|
356
392
|
---
|
|
357
393
|
|
|
@@ -361,32 +397,79 @@ status: current
|
|
|
361
397
|
|
|
362
398
|
**用途**: 记录重要的架构决策及其理由
|
|
363
399
|
|
|
364
|
-
|
|
400
|
+
**文件命名**: `NNN-kebab-case-title.md`(例如:`001-use-postgresql.md`)
|
|
365
401
|
|
|
366
402
|
**必要章节**:
|
|
367
403
|
|
|
368
404
|
| 章节 | 说明 | 必要性 |
|
|
369
405
|
|---------|-------------|----------|
|
|
370
406
|
| 标题 | 决策名称 | 必要 |
|
|
407
|
+
| 日期 | 决策日期(YYYY-MM-DD) | 必要 |
|
|
371
408
|
| 状态 | proposed/accepted/deprecated/superseded | 必要 |
|
|
409
|
+
| 决策者 | 制定或参与决策的人员 | 必要 |
|
|
372
410
|
| 背景 | 为何需要此决策 | 必要 |
|
|
373
411
|
| 决策 | 具体决策内容 | 必要 |
|
|
374
412
|
| 后果 | 决策的影响(正面/负面) | 必要 |
|
|
413
|
+
| 驱动因素 | 推动此决策的关键因素 | 建议 |
|
|
375
414
|
| 替代方案 | 考虑过的其他选项 | 建议 |
|
|
415
|
+
| 相关 ADR | 替代/被替代链接 | 如适用 |
|
|
416
|
+
|
|
417
|
+
#### ADR 生命周期
|
|
376
418
|
|
|
377
|
-
|
|
419
|
+
ADR 遵循具有明确状态转换的定义生命周期:
|
|
420
|
+
|
|
421
|
+
```
|
|
422
|
+
proposed → accepted → [deprecated | superseded]
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
| 状态 | 含义 | 转换 |
|
|
426
|
+
|--------|---------|------------|
|
|
427
|
+
| **proposed** | 讨论中,尚未决定 | → accepted 或已撤回 |
|
|
428
|
+
| **accepted** | 决策已生效 | → deprecated 或 superseded |
|
|
429
|
+
| **deprecated** | 决策不再相关 | 终态 |
|
|
430
|
+
| **superseded** | 被更新的 ADR 取代 | 必须链接至后续 ADR |
|
|
431
|
+
|
|
432
|
+
当 ADR 被取代时,添加一个链接到新 ADR 的 `superseded-by` 字段。新 ADR 应包含反向链接的 `supersedes` 字段。
|
|
433
|
+
|
|
434
|
+
#### 何时编写 ADR
|
|
435
|
+
|
|
436
|
+
使用此决策矩阵(影响度 × 可逆性)来确定是否需要 ADR:
|
|
437
|
+
|
|
438
|
+
| | 低影响度 | 高影响度 |
|
|
439
|
+
|---|:---------:|:----------:|
|
|
440
|
+
| **容易逆转** | ❌ 无需 ADR | ⚪ 可选 |
|
|
441
|
+
| **难以逆转** | ⚪ 可选 | ✅ 必须编写 ADR |
|
|
442
|
+
|
|
443
|
+
**“必须编写 ADR”的决策示例**:
|
|
444
|
+
- 选择数据库技术
|
|
445
|
+
- 采用新的框架或语言
|
|
446
|
+
- 定义 API 版本策略
|
|
447
|
+
- 更改认证机制
|
|
448
|
+
- 重大架构模式变更(单体架构 → 微服务)
|
|
449
|
+
|
|
450
|
+
#### ADR 模板(增强版)
|
|
378
451
|
|
|
379
452
|
```markdown
|
|
380
453
|
# ADR-001: [决策标题]
|
|
381
454
|
|
|
382
|
-
|
|
383
|
-
|
|
455
|
+
**日期**: YYYY-MM-DD
|
|
456
|
+
**状态**: proposed | accepted | deprecated | superseded
|
|
457
|
+
**决策者**: [参与人员列表]
|
|
458
|
+
**替代**: ADR-NNN(如适用)
|
|
459
|
+
**被替代**: ADR-NNN(如适用)
|
|
460
|
+
|
|
461
|
+
## 驱动因素
|
|
462
|
+
|
|
463
|
+
- [推动此决策的关键因素 1]
|
|
464
|
+
- [关键因素 2]
|
|
384
465
|
|
|
385
466
|
## 背景
|
|
386
|
-
|
|
467
|
+
|
|
468
|
+
[为何需要此决策。包括技术、业务和组织背景。]
|
|
387
469
|
|
|
388
470
|
## 决策
|
|
389
|
-
|
|
471
|
+
|
|
472
|
+
[做出的具体决策。请务必精确且无歧义。]
|
|
390
473
|
|
|
391
474
|
## 后果
|
|
392
475
|
|
|
@@ -398,173 +481,253 @@ status: current
|
|
|
398
481
|
- 缺点 1
|
|
399
482
|
- 缺点 2
|
|
400
483
|
|
|
401
|
-
##
|
|
402
|
-
|
|
403
|
-
|
|
484
|
+
## 考虑过的替代方案
|
|
485
|
+
|
|
486
|
+
### 替代方案 A: [名称]
|
|
487
|
+
- **优点**: ...
|
|
488
|
+
- **缺点**: ...
|
|
489
|
+
- **被拒绝原因**: ...
|
|
490
|
+
|
|
491
|
+
### 替代方案 B: [名称]
|
|
492
|
+
- **优点**: ...
|
|
493
|
+
- **缺点**: ...
|
|
494
|
+
- **被拒绝原因**: ...
|
|
495
|
+
|
|
496
|
+
## 参考资料
|
|
497
|
+
|
|
498
|
+
- [相关文档或外部资源]
|
|
404
499
|
```
|
|
405
500
|
|
|
406
501
|
---
|
|
407
502
|
|
|
408
|
-
##
|
|
503
|
+
## AI 协作文档
|
|
409
504
|
|
|
410
|
-
###
|
|
505
|
+
### 概述
|
|
411
506
|
|
|
412
|
-
|
|
413
|
-
|------|----------|
|
|
414
|
-
| 语言 | 繁体中文 |
|
|
415
|
-
| 编码 | UTF-8 |
|
|
416
|
-
| 行长度 | 建议 ≤ 120 字元 |
|
|
417
|
-
| 图表 | 优先使用 Mermaid,次之 ASCII Art |
|
|
418
|
-
| 连结 | 内部连结使用相对路径 |
|
|
507
|
+
现代文档必须针对人类读者与 AI 助手同时进行优化。本节提供了编写便于 AI 工具高效解析和利用的文档的指南。
|
|
419
508
|
|
|
420
|
-
###
|
|
509
|
+
### Token 感知文档设计
|
|
421
510
|
|
|
422
|
-
|
|
423
|
-
|------|----------|
|
|
424
|
-
| 同步更新 | 程序码变更时同步更新文件 |
|
|
425
|
-
| 版本标记 | 文件顶部标记版本与更新日期 |
|
|
426
|
-
| 审查纳入 | 程序码审查需包含文件变更 |
|
|
427
|
-
| 定期检视 | 每季检视文件是否过时 |
|
|
511
|
+
AI 模型存在上下文窗口限制。组织文档结构以供 LLM 高效消耗:
|
|
428
512
|
|
|
429
|
-
|
|
513
|
+
**文档结构原则**:
|
|
430
514
|
|
|
431
|
-
|
|
515
|
+
| 原则 | 说明 | 示例 |
|
|
516
|
+
|-----------|-------------|---------|
|
|
517
|
+
| **前置关键信息** | 将关键信息放在开头 | 先摘要后细节 |
|
|
518
|
+
| **使用清晰标题** | 层级结构有助于导航 | H1 > H2 > H3 递进 |
|
|
519
|
+
| **保持章节原子化** | 每个章节自成一体 | 可独立阅读 |
|
|
520
|
+
| **最小化冗余** | 避免重复信息 | 引用而非复制 |
|
|
521
|
+
| **使用结构化格式** | 优先使用表格和列表而非散文叙述 | 便于解析和提取 |
|
|
432
522
|
|
|
433
|
-
|
|
434
|
-
- [ ] 无过时或错误资讯
|
|
435
|
-
- [ ] 所有连结有效
|
|
436
|
-
- [ ] 范例可执行/正确
|
|
437
|
-
- [ ] 格式符合标准
|
|
523
|
+
**建议文档规模**:
|
|
438
524
|
|
|
439
|
-
|
|
525
|
+
| 文档类型 | 目标规模 | 理由 |
|
|
526
|
+
|---------------|-------------|-----------|
|
|
527
|
+
| README | 500-1000 词 | 快速概览 |
|
|
528
|
+
| API 端点文档 | 每个端点 200-400 词 | 聚焦且易于扫读 |
|
|
529
|
+
| 架构文档 | 每个章节 1000-2000 词 | 详尽但分块清晰 |
|
|
530
|
+
| ADR | 300-600 词 | 聚焦决策 |
|
|
440
531
|
|
|
441
|
-
|
|
532
|
+
### AI 友好文档模式
|
|
442
533
|
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
├── CONTRIBUTING.md # 贡献指南
|
|
447
|
-
├── CHANGELOG.md # 变更日志
|
|
448
|
-
├── .standards/ or .claude/ # 开发标准
|
|
449
|
-
│ ├── documentation-writing-standards.md
|
|
450
|
-
│ └── ...
|
|
451
|
-
└── docs/ # 文件目录
|
|
452
|
-
├── INDEX.md # 文件索引
|
|
453
|
-
├── ARCHITECTURE.md # 架构文件
|
|
454
|
-
├── API.md # API 文件
|
|
455
|
-
├── DATABASE.md # 资料库文件
|
|
456
|
-
├── DEPLOYMENT.md # 部署文件
|
|
457
|
-
├── MIGRATION.md # 迁移文件
|
|
458
|
-
├── ADR/ # 架构决策记录
|
|
459
|
-
│ ├── 001-xxx.md
|
|
460
|
-
│ └── ...
|
|
461
|
-
└── DB/ # 资料库脚本
|
|
462
|
-
```
|
|
534
|
+
**模式 1:结构化元数据块**
|
|
535
|
+
|
|
536
|
+
在文档顶部包含机器可读的元数据:
|
|
463
537
|
|
|
538
|
+
```markdown
|
|
464
539
|
---
|
|
540
|
+
title: User Authentication API
|
|
541
|
+
version: 2.1.0
|
|
542
|
+
last_updated: 2026-01-24
|
|
543
|
+
owner: auth-team
|
|
544
|
+
status: stable
|
|
545
|
+
dependencies:
|
|
546
|
+
- user-service
|
|
547
|
+
- token-service
|
|
548
|
+
---
|
|
549
|
+
```
|
|
465
550
|
|
|
466
|
-
|
|
551
|
+
**模式 2:清晰的章节标记**
|
|
467
552
|
|
|
468
|
-
|
|
469
|
-
|---------|-------|
|
|
470
|
-
| Markdown 编辑 | VS Code + Markdown Preview Enhanced |
|
|
471
|
-
| 图表绘制 | Mermaid / draw.io / PlantUML |
|
|
472
|
-
| API 文档 | OpenAPI (Swagger) / Redoc |
|
|
473
|
-
| ER 图 | dbdiagram.io / DBeaver |
|
|
553
|
+
使用 AI 能够识别的一致章节标头:
|
|
474
554
|
|
|
475
|
-
|
|
555
|
+
```markdown
|
|
556
|
+
## Overview
|
|
557
|
+
[Brief description of what this component/API does]
|
|
476
558
|
|
|
477
|
-
##
|
|
559
|
+
## Quick Start
|
|
560
|
+
[Minimal steps to get started]
|
|
478
561
|
|
|
479
|
-
|
|
562
|
+
## API Reference
|
|
563
|
+
[Detailed API documentation]
|
|
480
564
|
|
|
481
|
-
|
|
565
|
+
## Configuration
|
|
566
|
+
[Configuration options and defaults]
|
|
482
567
|
|
|
483
|
-
|
|
568
|
+
## Troubleshooting
|
|
569
|
+
[Common issues and solutions]
|
|
570
|
+
```
|
|
484
571
|
|
|
485
|
-
|
|
486
|
-
|------|------|
|
|
487
|
-
| **前置重要信息** | 关键信息放在文档开头 |
|
|
488
|
-
| **结构化数据** | 使用表格、列表、代码块 |
|
|
489
|
-
| **明确标记** | 使用清晰的章节标题 |
|
|
490
|
-
| **避免冗余** | 减少重复内容 |
|
|
572
|
+
**模式 3:明确的示例**
|
|
491
573
|
|
|
492
|
-
|
|
574
|
+
提供带有清晰上下文的完整、可运行示例:
|
|
493
575
|
|
|
494
576
|
```markdown
|
|
577
|
+
### Example: Create User
|
|
578
|
+
|
|
579
|
+
**Prerequisites**:
|
|
580
|
+
- Valid API key
|
|
581
|
+
- Admin role
|
|
582
|
+
|
|
583
|
+
**Request**:
|
|
584
|
+
```bash
|
|
585
|
+
curl -X POST https://api.example.com/v1/users \
|
|
586
|
+
-H "Authorization: Bearer $API_KEY" \
|
|
587
|
+
-H "Content-Type: application/json" \
|
|
588
|
+
-d '{"name": "John", "email": "john@example.com"}'
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
**Response** (201 Created):
|
|
592
|
+
```json
|
|
593
|
+
{
|
|
594
|
+
"id": "usr_123",
|
|
595
|
+
"name": "John",
|
|
596
|
+
"email": "john@example.com",
|
|
597
|
+
"created_at": "2026-01-24T10:30:00Z"
|
|
598
|
+
}
|
|
599
|
+
```
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
### 面向 LLM 优化的编写规则
|
|
603
|
+
|
|
604
|
+
当编写将由 LLM 消耗(通过 RAG、上下文注入或直接阅读)的文档时,遵循以下规则以最大化理解准确度:
|
|
605
|
+
|
|
606
|
+
| 规则 | 说明 | 示例 |
|
|
607
|
+
|------|-------------|---------|
|
|
608
|
+
| **短段落** | 段落保持在 3-5 行 | 将冗长解释拆分为多个段落 |
|
|
609
|
+
| **术语一致** | 全文对同一概念使用相同术语 | 始终使用 "user",而非有时用 "user" 有时用 "customer" |
|
|
610
|
+
| **代码附带语言标签** | 始终在围栏式代码块中指定语言 | ` ```javascript ` 而非 ` ``` ` |
|
|
611
|
+
| **避免代词模糊** | 跨段落引用时使用明确的名词代替 "it"、"this"、"that" | "The auth service validates..." 而非 "It validates..." |
|
|
612
|
+
| **上下文自给自足** | 每个 H2 章节应在不阅读前置章节的情况下即可被理解 | 包含必要的上下文或交叉引用 |
|
|
613
|
+
| **明确否定** | 当区分具有重要意义时,说明某物“不是”什么 | "This endpoint creates users but does NOT send welcome emails" |
|
|
614
|
+
|
|
615
|
+
### 文档分块指南
|
|
616
|
+
|
|
617
|
+
对于由检索增强生成(RAG)系统消耗的文档,组织内容结构以产生有效的分块:
|
|
618
|
+
|
|
619
|
+
- **H2 章节 ≤ 4K tokens**(约 3000 词):每个 H2 章节应为一个自包含的分块
|
|
620
|
+
- **每个 H2 一个主题**:避免在单个章节中混杂无关概念
|
|
621
|
+
- **前置摘要**:以 1-2 句话的摘要开启每个章节
|
|
622
|
+
|
|
623
|
+
**易于检索的元数据**(可选的 YAML 前置元数据):
|
|
624
|
+
|
|
625
|
+
```yaml
|
|
495
626
|
---
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
627
|
+
title: User Authentication API
|
|
628
|
+
scope: auth-service
|
|
629
|
+
difficulty: intermediate
|
|
630
|
+
tags: [authentication, API, OAuth2, JWT]
|
|
631
|
+
last_validated: 2026-03-17
|
|
501
632
|
---
|
|
633
|
+
```
|
|
502
634
|
|
|
503
|
-
|
|
504
|
-
## 快速参考
|
|
505
|
-
[最常用的信息放这里]
|
|
506
|
-
<!-- AI-SECTION-END: quick-reference -->
|
|
635
|
+
这些元数据字段有助于检索系统按相关性对文档进行排序和筛选。
|
|
507
636
|
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
<!-- AI-SECTION-END: details -->
|
|
512
|
-
```
|
|
637
|
+
### 为 AI 代码生成编写文档
|
|
638
|
+
|
|
639
|
+
当文档将用于生成代码时:
|
|
513
640
|
|
|
514
|
-
|
|
641
|
+
**包含明确约束**:
|
|
515
642
|
|
|
516
|
-
|
|
643
|
+
```markdown
|
|
644
|
+
## Validation Rules
|
|
645
|
+
|
|
646
|
+
| Field | Type | Constraints |
|
|
647
|
+
|-------|------|-------------|
|
|
648
|
+
| email | string | Required, valid email format, max 255 chars |
|
|
649
|
+
| age | integer | Required, range 0-150 |
|
|
650
|
+
| role | string | Enum: "admin", "user", "guest" |
|
|
651
|
+
```
|
|
517
652
|
|
|
518
|
-
|
|
653
|
+
**明确错误场景**:
|
|
519
654
|
|
|
520
655
|
```markdown
|
|
521
|
-
##
|
|
656
|
+
## Error Responses
|
|
522
657
|
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
658
|
+
| Scenario | HTTP Status | Error Code | Message |
|
|
659
|
+
|----------|-------------|------------|---------|
|
|
660
|
+
| Invalid email | 400 | INVALID_EMAIL | "Email format is invalid" |
|
|
661
|
+
| User exists | 409 | DUPLICATE_USER | "User with this email already exists" |
|
|
662
|
+
| Missing auth | 401 | UNAUTHORIZED | "Authentication required" |
|
|
663
|
+
```
|
|
527
664
|
|
|
528
|
-
|
|
529
|
-
返回 HTTP 201 和用户对象(不含密码)
|
|
665
|
+
**阐明业务逻辑**:
|
|
530
666
|
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
667
|
+
```markdown
|
|
668
|
+
## Discount Calculation Logic
|
|
669
|
+
|
|
670
|
+
1. Base discount = 0%
|
|
671
|
+
2. If customer type is "VIP", add 20%
|
|
672
|
+
3. If order total > $100, add 5%
|
|
673
|
+
4. If coupon code is valid, add coupon discount
|
|
674
|
+
5. Maximum total discount = 50%
|
|
675
|
+
6. Apply discount to subtotal (not including tax)
|
|
534
676
|
```
|
|
535
677
|
|
|
536
|
-
|
|
678
|
+
### AI 提示词集成
|
|
679
|
+
|
|
680
|
+
对于定义 AI 辅助工作流的文档:
|
|
681
|
+
|
|
682
|
+
**嵌入式提示词模板**:
|
|
683
|
+
|
|
684
|
+
```markdown
|
|
685
|
+
## AI Code Review Prompt
|
|
537
686
|
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
687
|
+
When reviewing code changes, use this prompt:
|
|
688
|
+
|
|
689
|
+
```
|
|
690
|
+
Review this code change for:
|
|
691
|
+
1. Security vulnerabilities (OWASP Top 10)
|
|
692
|
+
2. Performance issues
|
|
693
|
+
3. Error handling completeness
|
|
694
|
+
4. Adherence to [project-conventions.md]
|
|
695
|
+
|
|
696
|
+
Provide feedback in this format:
|
|
697
|
+
- 🔴 Critical: [Must fix before merge]
|
|
698
|
+
- 🟡 Important: [Should address]
|
|
699
|
+
- 🟢 Suggestion: [Nice to have]
|
|
700
|
+
```
|
|
701
|
+
```
|
|
543
702
|
|
|
544
703
|
---
|
|
545
704
|
|
|
546
705
|
## API 文档标准
|
|
547
706
|
|
|
548
|
-
### OpenAPI 3.1
|
|
707
|
+
### OpenAPI 3.1 合规性
|
|
708
|
+
|
|
709
|
+
对于 REST API,请使用 OpenAPI 3.1(与 JSON Schema draft 2020-12 完全对齐):
|
|
710
|
+
|
|
711
|
+
**OpenAPI 3.1 主要特性**:
|
|
712
|
+
|
|
713
|
+
| 特性 | 描述 |
|
|
714
|
+
|---------|-------------|
|
|
715
|
+
| JSON Schema 对齐 | 与 JSON Schema 完全兼容 |
|
|
716
|
+
| Webhook 支持 | 原生 Webhook 文档支持 |
|
|
717
|
+
| `type` 数组 | 支持 `"type": ["string", "null"]` |
|
|
718
|
+
| 与属性同级的 `$ref` | 在同一对象中引用并扩展 |
|
|
719
|
+
|
|
720
|
+
**OpenAPI 3.1 Schema 示例**:
|
|
549
721
|
|
|
550
722
|
```yaml
|
|
551
723
|
openapi: 3.1.0
|
|
552
724
|
info:
|
|
553
|
-
title:
|
|
554
|
-
version: 1.0
|
|
555
|
-
description: |
|
|
556
|
-
## 概述
|
|
557
|
-
此 API 提供用户管理功能。
|
|
558
|
-
|
|
559
|
-
## 认证
|
|
560
|
-
使用 Bearer Token 认证。
|
|
561
|
-
|
|
725
|
+
title: User API
|
|
726
|
+
version: 2.1.0
|
|
562
727
|
paths:
|
|
563
728
|
/users:
|
|
564
729
|
post:
|
|
565
|
-
summary:
|
|
566
|
-
operationId: createUser
|
|
567
|
-
tags: [Users]
|
|
730
|
+
summary: Create a new user
|
|
568
731
|
requestBody:
|
|
569
732
|
required: true
|
|
570
733
|
content:
|
|
@@ -573,57 +736,292 @@ paths:
|
|
|
573
736
|
$ref: '#/components/schemas/CreateUserRequest'
|
|
574
737
|
responses:
|
|
575
738
|
'201':
|
|
576
|
-
description:
|
|
739
|
+
description: User created
|
|
577
740
|
content:
|
|
578
741
|
application/json:
|
|
579
742
|
schema:
|
|
580
743
|
$ref: '#/components/schemas/User'
|
|
744
|
+
components:
|
|
745
|
+
schemas:
|
|
746
|
+
CreateUserRequest:
|
|
747
|
+
type: object
|
|
748
|
+
required: [name, email]
|
|
749
|
+
properties:
|
|
750
|
+
name:
|
|
751
|
+
type: string
|
|
752
|
+
minLength: 1
|
|
753
|
+
maxLength: 100
|
|
754
|
+
email:
|
|
755
|
+
type: string
|
|
756
|
+
format: email
|
|
581
757
|
```
|
|
582
758
|
|
|
583
|
-
### AsyncAPI 2.6
|
|
759
|
+
### 用于事件驱动 API 的 AsyncAPI 2.6
|
|
760
|
+
|
|
761
|
+
对于基于消息/事件驱动的 API,请使用 AsyncAPI 2.6:
|
|
762
|
+
|
|
763
|
+
**AsyncAPI 文档示例**:
|
|
584
764
|
|
|
585
765
|
```yaml
|
|
586
766
|
asyncapi: 2.6.0
|
|
587
767
|
info:
|
|
588
|
-
title:
|
|
768
|
+
title: Order Events
|
|
589
769
|
version: 1.0.0
|
|
590
|
-
|
|
591
770
|
channels:
|
|
592
|
-
|
|
771
|
+
orders/created:
|
|
593
772
|
publish:
|
|
594
|
-
summary: 用户创建事件
|
|
595
773
|
message:
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
774
|
+
$ref: '#/components/messages/OrderCreated'
|
|
775
|
+
components:
|
|
776
|
+
messages:
|
|
777
|
+
OrderCreated:
|
|
778
|
+
payload:
|
|
779
|
+
type: object
|
|
780
|
+
properties:
|
|
781
|
+
orderId:
|
|
782
|
+
type: string
|
|
783
|
+
customerId:
|
|
784
|
+
type: string
|
|
785
|
+
totalAmount:
|
|
786
|
+
type: number
|
|
787
|
+
createdAt:
|
|
788
|
+
type: string
|
|
789
|
+
format: date-time
|
|
604
790
|
```
|
|
605
791
|
|
|
606
792
|
---
|
|
607
793
|
|
|
794
|
+
## 易于翻译的写作规范
|
|
795
|
+
|
|
796
|
+
对于维护多语言文档的项目,请在源文档中遵循以下写作规则,以提高翻译质量并减少翻译人员的工作量。
|
|
797
|
+
|
|
798
|
+
### 写作规则
|
|
799
|
+
|
|
800
|
+
| 规则 | 描述 | 示例 |
|
|
801
|
+
|------|-------------|---------|
|
|
802
|
+
| **完整句子** | 避免使用句子片段和电报式风格 | "The service restarts automatically." 而非 "Auto-restart." |
|
|
803
|
+
| **避免习语和俚语** | 使用字面、国际通用的语言 | "Easy to use" 而非 "A piece of cake" |
|
|
804
|
+
| **术语一致性** | 为项目术语创建并遵循词汇表 | 始终使用 "deployment",而不是有时用 "deployment" 有时用 "release" |
|
|
805
|
+
| **简单句结构** | 优先使用 SVO(主-谓-宾)结构;避免嵌套从句 | "The API returns JSON." 而非 "The JSON that the API, when called correctly, returns..." |
|
|
806
|
+
| **指代明确** | 避免跨句子使用模棱两可的代词 | "The server processes the request." 而非 "It processes it." |
|
|
807
|
+
|
|
808
|
+
### 词汇表模板
|
|
809
|
+
|
|
810
|
+
维护一个 `glossary.md` 文件,以确保各翻译版本之间的术语一致性:
|
|
811
|
+
|
|
812
|
+
```markdown
|
|
813
|
+
# Project Glossary
|
|
814
|
+
|
|
815
|
+
| English Term | Definition | Translation Notes |
|
|
816
|
+
|-------------|------------|-------------------|
|
|
817
|
+
| deployment | The process of releasing software to production | 部署 (zh-TW) |
|
|
818
|
+
| endpoint | A specific URL path in an API | 端點 (zh-TW) |
|
|
819
|
+
| rollback | Reverting to a previous version | 回滾 (zh-TW) |
|
|
820
|
+
```
|
|
821
|
+
|
|
822
|
+
### 翻译状态 Frontmatter
|
|
823
|
+
|
|
824
|
+
在已翻译文档的头部跟踪翻译状态:
|
|
825
|
+
|
|
826
|
+
```yaml
|
|
827
|
+
---
|
|
828
|
+
translation_status: current | needs_update | in_progress
|
|
829
|
+
source_version: 1.2.0
|
|
830
|
+
source_hash: a1b2c3d4e5f6 # first 12 chars of `git hash-object <source>`
|
|
831
|
+
translated_by: human | machine | machine+human-review
|
|
832
|
+
last_synced: 2026-03-17
|
|
833
|
+
---
|
|
834
|
+
```
|
|
835
|
+
|
|
836
|
+
| 字段 | 描述 |
|
|
837
|
+
|-------|-------------|
|
|
838
|
+
| `translation_status` | 翻译是否与当前源文档相符 |
|
|
839
|
+
| `source_version` | 翻译所对应的源文档版本 |
|
|
840
|
+
| `source_hash` | 翻译时源文件的 Git 哈希值(用于精确跟踪) |
|
|
841
|
+
| `translated_by` | 用于质量评估的翻译方式 |
|
|
842
|
+
| `last_synced` | 上次同步检查的日期 |
|
|
843
|
+
|
|
844
|
+
---
|
|
845
|
+
|
|
846
|
+
## 质量标准
|
|
847
|
+
|
|
848
|
+
### 格式要求
|
|
849
|
+
|
|
850
|
+
| 项目 | 标准 |
|
|
851
|
+
|------|----------|
|
|
852
|
+
| 语言 | 英文 |
|
|
853
|
+
| 编码 | UTF-8 |
|
|
854
|
+
| 行长度 | 建议 ≤ 120 字符 |
|
|
855
|
+
| 图表 | 优先使用 Mermaid,次之 ASCII Art |
|
|
856
|
+
| 链接 | 内部链接使用相对路径 |
|
|
857
|
+
|
|
858
|
+
### 维护要求
|
|
859
|
+
|
|
860
|
+
| 项目 | 标准 |
|
|
861
|
+
|------|----------|
|
|
862
|
+
| 同步更新 | **AI 自动行为**:完成代码变更后,AI 必须检查哪些文档受到影响,并将其列出作为提醒。参见下方的 [AI 行为:文档影响自动检查](#automatic-documentation-impact-check) |
|
|
863
|
+
| 版本标记 | 文档顶部标记版本与更新日期 |
|
|
864
|
+
| 审查纳入 | 代码审查需包含文档变更 |
|
|
865
|
+
| 定期审查 | 每季度审查文档是否过时 |
|
|
866
|
+
|
|
867
|
+
### 文档影响自动检查
|
|
868
|
+
|
|
869
|
+
**这是 AI 的自动行为**——AI 助手在完成任何代码修改任务后,必须执行此项检查,无需等待用户询问。
|
|
870
|
+
|
|
871
|
+
**工作流程:**
|
|
872
|
+
|
|
873
|
+
1. 完成代码变更后,确定修改了哪些文件
|
|
874
|
+
2. 对每个被修改的文件,检查是否有任何文档引用了它(README、CLI 文档、API 文档、规格、技能、翻译)
|
|
875
|
+
3. 如果发现受影响的文档,追加包含**建议命令**的提醒区块:
|
|
876
|
+
|
|
877
|
+
```
|
|
878
|
+
---
|
|
879
|
+
📋 **Documentation Impact**
|
|
880
|
+
The following documents may need updating:
|
|
881
|
+
- `README.md` — describes changed CLI option `--xxx`
|
|
882
|
+
→ `/docs readme`
|
|
883
|
+
- `docs/CLI-INIT-OPTIONS.md` — references modified function `promptXxx()`
|
|
884
|
+
→ manual update or `/docs generate`
|
|
885
|
+
- `locales/zh-TW/docs/CLI-INIT-OPTIONS.md` — translation of modified source
|
|
886
|
+
→ `/docs translate docs/CLI-INIT-OPTIONS.md --lang zh-TW`
|
|
887
|
+
|
|
888
|
+
Or run `/docs impact` for a full analysis.
|
|
889
|
+
---
|
|
890
|
+
```
|
|
891
|
+
|
|
892
|
+
4. 如果没有受影响的文档,则静默跳过
|
|
893
|
+
5. **不要自动修改文档**——仅列出提醒并等待用户确认
|
|
894
|
+
|
|
895
|
+
**命令建议映射:**
|
|
896
|
+
|
|
897
|
+
| 受影响文档 | 建议命令 |
|
|
898
|
+
|-------------------|-------------------|
|
|
899
|
+
| README.md | `/docs readme` |
|
|
900
|
+
| API 文档 | `/docs api` |
|
|
901
|
+
| 生成的文档(速查表、参考) | `/docs generate` |
|
|
902
|
+
| 翻译文件(`locales/`) | `/docs translate <source-file> --lang <lang>` |
|
|
903
|
+
| 规格文件、技能文件、其他文档 | 手动更新(建议具体文件路径) |
|
|
904
|
+
| 多个文档受影响 | `/docs impact` 获取完整概览 |
|
|
905
|
+
|
|
906
|
+
**检查范围:**
|
|
907
|
+
|
|
908
|
+
| 文档类型 | 对照检查项 |
|
|
909
|
+
|--------------|---------------|
|
|
910
|
+
| CLI 文档(`docs/`) | 修改的函数、CLI 选项、命令 |
|
|
911
|
+
| 规格文件(`docs/specs/`) | 修改的接口、Schema、工作流 |
|
|
912
|
+
| 技能(`skills/`) | 修改的行为、标准引用 |
|
|
913
|
+
| 翻译(`locales/`) | 任何具有翻译的已修改源文件 |
|
|
914
|
+
| README、CHANGELOG | 修改的公开 API、功能、配置 |
|
|
915
|
+
|
|
916
|
+
### 审查清单
|
|
917
|
+
|
|
918
|
+
提交文档前:
|
|
919
|
+
|
|
920
|
+
- [ ] 必要章节完整
|
|
921
|
+
- [ ] 无过时或错误信息
|
|
922
|
+
- [ ] 所有链接有效
|
|
923
|
+
- [ ] 示例可执行/准确
|
|
924
|
+
- [ ] 格式符合标准
|
|
925
|
+
|
|
926
|
+
### 文档质量指标
|
|
927
|
+
|
|
928
|
+
使用领先指标和滞后指标量化文档健康度。
|
|
929
|
+
|
|
930
|
+
#### 领先指标(前瞻性)
|
|
931
|
+
|
|
932
|
+
| 指标 | 目标 | 测量方式 | 自动化 |
|
|
933
|
+
|--------|--------|----------------|------------|
|
|
934
|
+
| **覆盖率** | ≥ 90% 的公开 API 已撰写文档 | 统计已有文档的端点数与端点总数 | 自定义脚本或 API 规格 diff |
|
|
935
|
+
| **新鲜度** | 所有文档在 90 天内更新 | 检查文档头部的 `Last Updated` 日期 | `find` + 日期比较脚本 |
|
|
936
|
+
| **链接健康度** | 100% 有效链接 | 检查所有内部与外部链接 | markdown-link-check、lychee |
|
|
937
|
+
| **示例有效性** | 100% 的代码示例运行成功 | 提取并执行代码块 | doctest、自定义 CI 脚本 |
|
|
938
|
+
| **结构合规性** | 所有文档具有必要章节 | 对照章节模板进行验证 | remark-lint、自定义 linter |
|
|
939
|
+
|
|
940
|
+
#### 滞后指标(结果性)
|
|
941
|
+
|
|
942
|
+
| 指标 | 描述 | 测量方式 |
|
|
943
|
+
|--------|-------------|----------------|
|
|
944
|
+
| **支持工单减少** | 关于已有文档记录功能的问题减少 | 跟踪标记为“documentation”的支持工单 |
|
|
945
|
+
| **新手入职时间** | 新开发者提交第一个 PR 的时间 | 测量入职团队队列的平均值 |
|
|
946
|
+
| **文档相关 PR 评论** | 要求补充文档的审查评论减少 | 统计提及“docs”的 PR 审查评论数 |
|
|
947
|
+
|
|
948
|
+
#### 推荐自动化工具
|
|
949
|
+
|
|
950
|
+
| 工具 | 用途 | 集成 |
|
|
951
|
+
|------|---------|-------------|
|
|
952
|
+
| **markdown-link-check** | 验证 Markdown 文件中的链接 | Pre-commit hook、CI |
|
|
953
|
+
| **lychee** | 快速链接检查器(基于 Rust) | CI 流水线 |
|
|
954
|
+
| **remark-lint** | Markdown 风格与结构检查 | Pre-commit hook |
|
|
955
|
+
| **textstat** | 可读性评分(Flesch-Kincaid 等) | CI 流水线(参考建议) |
|
|
956
|
+
| **vale** | 文本检查(风格、语法、术语) | Pre-commit hook、CI |
|
|
957
|
+
|
|
958
|
+
---
|
|
959
|
+
|
|
960
|
+
## 文件位置规范
|
|
961
|
+
|
|
962
|
+
```
|
|
963
|
+
project-root/
|
|
964
|
+
├── README.md # Project entry document
|
|
965
|
+
├── CONTRIBUTING.md # Contribution guide
|
|
966
|
+
├── CHANGELOG.md # Change log
|
|
967
|
+
├── .standards/ or .claude/ # Development standards
|
|
968
|
+
│ ├── documentation-writing-standards.md
|
|
969
|
+
│ └── ...
|
|
970
|
+
└── docs/ # Documentation directory
|
|
971
|
+
├── INDEX.md # Documentation index
|
|
972
|
+
├── ARCHITECTURE.md # Architecture document
|
|
973
|
+
├── API.md # API document
|
|
974
|
+
├── DATABASE.md # Database document
|
|
975
|
+
├── DEPLOYMENT.md # Deployment document
|
|
976
|
+
├── MIGRATION.md # Migration document
|
|
977
|
+
├── ADR/ # Architecture decision records
|
|
978
|
+
│ ├── 001-xxx.md
|
|
979
|
+
│ └── ...
|
|
980
|
+
└── DB/ # Database scripts
|
|
981
|
+
```
|
|
982
|
+
|
|
983
|
+
---
|
|
984
|
+
|
|
985
|
+
## 推荐工具
|
|
986
|
+
|
|
987
|
+
| 用途 | 工具 |
|
|
988
|
+
|---------|-------|
|
|
989
|
+
| Markdown 编辑 | VS Code + Markdown Preview Enhanced |
|
|
990
|
+
| 图表绘制 | Mermaid / draw.io / PlantUML |
|
|
991
|
+
| API 文档 | OpenAPI (Swagger) / Redoc |
|
|
992
|
+
| ER 图 | dbdiagram.io / DBeaver |
|
|
993
|
+
|
|
994
|
+
---
|
|
995
|
+
|
|
608
996
|
## 文档可及性
|
|
609
997
|
|
|
610
998
|
确保文档对所有用户都可访问,在适用的情况下遵循 WCAG 2.1 Level A 指南。
|
|
611
999
|
|
|
612
1000
|
| 需求 | 描述 | 示例 |
|
|
613
|
-
|
|
614
|
-
| **浅显语言** | 使用清晰、简单的语言;目标为 8
|
|
615
|
-
| **图片替代文字** | 为所有非装饰性图片提供描述性替代文字 | `` |
|
|
1004
|
+
| **标题层级** | 使用正确的标题层级(h1→h2→h3),切勿跳级 | 不要从 `#` 直接跳到 `###` |
|
|
1005
|
+
| **链接文字** | 使用描述性链接文字,而非“点击此处” | 避免:[click here] → 使用:[installation guide] |
|
|
1006
|
+
| **代码块** | 使用带语言标识符的围栏式代码块 | ` ```javascript ` 而非 ` ``` ` |
|
|
1007
|
+
| **色彩独立性** | 不要仅依赖色彩传达意义 | 在色彩旁搭配使用 ✅/❌ 图标 |
|
|
620
1008
|
|
|
621
1009
|
---
|
|
622
1010
|
|
|
623
1011
|
## 相关标准
|
|
624
1012
|
|
|
625
|
-
- [
|
|
626
|
-
- [
|
|
1013
|
+
- [文档结构标准](documentation-structure.md)
|
|
1014
|
+
- [变更日志标准](changelog-standards.md)
|
|
1015
|
+
|
|
1016
|
+
---
|
|
1017
|
+
|
|
1018
|
+
## 参考资料
|
|
1019
|
+
|
|
1020
|
+
- [OpenAPI 3.1 规范](https://spec.openapis.org/oas/v3.1.0) - 最新 OpenAPI 规范
|
|
1021
|
+
- [AsyncAPI 2.6 规范](https://www.asyncapi.com/docs/reference/specification/v2.6.0) - 事件驱动 API 文档
|
|
1022
|
+
- [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html) - JSON Schema 规范
|
|
1023
|
+
- [Diátaxis 文档框架](https://diataxis.fr/) - 文档结构方法论
|
|
1024
|
+
- [Write the Docs](https://www.writethedocs.org/guide/) - 文档社区最佳实践
|
|
627
1025
|
|
|
628
1026
|
---
|
|
629
1027
|
|
|
@@ -631,21 +1029,13 @@ channels:
|
|
|
631
1029
|
|
|
632
1030
|
| 版本 | 日期 | 变更内容 |
|
|
633
1031
|
|---------|------|---------|
|
|
634
|
-
| 1.
|
|
1032
|
+
| 1.2.0 | 2026-03-17 | 新增:增强版 ADR 模板(生命周期、决策矩阵、替代链接)、针对 LLM 优化的撰写规则、文档分块指南、利于翻译的撰写标准、文档质量指标(领先/滞后指标) |
|
|
1033
|
+
| 1.1.0 | 2026-01-24 | 新增:AI 协作文档章节、Token 感知文档设计、API 文档标准(OpenAPI 3.1、AsyncAPI 2.6) |
|
|
635
1034
|
| 1.0.1 | 2025-12-24 | 新增:相关标准章节 |
|
|
636
1035
|
| 1.0.0 | 2025-12-10 | 初版文档撰写标准 |
|
|
637
1036
|
|
|
638
1037
|
---
|
|
639
1038
|
|
|
640
|
-
## 参考资料
|
|
641
|
-
|
|
642
|
-
- [OpenAPI 3.1 规范](https://spec.openapis.org/oas/v3.1.0) - RESTful API 描述标准
|
|
643
|
-
- [AsyncAPI 2.6 规范](https://www.asyncapi.com/docs/reference/specification/v2.6.0) - 异步 API 描述标准
|
|
644
|
-
- [JSON Schema](https://json-schema.org/) - 数据验证标准
|
|
645
|
-
- [Diátaxis 文档框架](https://diataxis.fr/) - 技术文档组织方法
|
|
646
|
-
|
|
647
|
-
---
|
|
648
|
-
|
|
649
1039
|
## 授权
|
|
650
1040
|
|
|
651
1041
|
本标准以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权发布。
|