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.
Files changed (721) hide show
  1. package/bin/uds.js +12 -1
  2. package/bundled/ai/options/commit-message/traditional-chinese.ai.yaml +69 -67
  3. package/bundled/ai/standards/commit-message.ai.yaml +12 -2
  4. package/bundled/ai/standards/mock-boundary.ai.yaml +138 -2
  5. package/bundled/ai/standards/secret-management-standards.ai.yaml +12 -1
  6. package/bundled/ai/standards/turn-completion-integrity.ai.yaml +6 -2
  7. package/bundled/core/commit-message-guide.md +22 -19
  8. package/bundled/core/mock-boundary.md +70 -2
  9. package/bundled/core/secret-management-standards.md +13 -1
  10. package/bundled/core/turn-completion-integrity.md +8 -2
  11. package/bundled/extensions/locales/zh-tw.md +19 -19
  12. package/bundled/hooks/check-dangerous-cmd.mjs +161 -26
  13. package/bundled/hooks/check-logging-standard.mjs +35 -6
  14. package/bundled/hooks/validate-commit-msg.mjs +317 -28
  15. package/bundled/locales/zh-CN/CHANGELOG.md +2323 -1099
  16. package/bundled/locales/zh-CN/CLAUDE.md +987 -101
  17. package/bundled/locales/zh-CN/README.md +3 -3
  18. package/bundled/locales/zh-CN/SECURITY.md +4 -3
  19. package/bundled/locales/zh-CN/STANDARDS-MAPPING.md +103 -6
  20. package/bundled/locales/zh-CN/adoption/ADOPTION-GUIDE.md +68 -97
  21. package/bundled/locales/zh-CN/adoption/DAILY-WORKFLOW-GUIDE.md +2 -1
  22. package/bundled/locales/zh-CN/adoption/STATIC-DYNAMIC-GUIDE.md +8 -9
  23. package/bundled/locales/zh-CN/adoption/checklists/enterprise.md +81 -80
  24. package/bundled/locales/zh-CN/adoption/checklists/minimal.md +18 -14
  25. package/bundled/locales/zh-CN/adoption/checklists/recommended.md +49 -46
  26. package/bundled/locales/zh-CN/ai/MAINTENANCE.md +44 -9
  27. package/bundled/locales/zh-CN/ai/options/commit-message/traditional-chinese.ai.yaml +63 -55
  28. package/bundled/locales/zh-CN/core/acceptance-criteria-traceability.md +61 -14
  29. package/bundled/locales/zh-CN/core/acceptance-test-driven-development.md +2 -1
  30. package/bundled/locales/zh-CN/core/accessibility-standards.md +871 -62
  31. package/bundled/locales/zh-CN/core/adr-standards.md +155 -32
  32. package/bundled/locales/zh-CN/core/agent-communication-protocol.md +2 -1
  33. package/bundled/locales/zh-CN/core/agent-dispatch.md +68 -33
  34. package/bundled/locales/zh-CN/core/ai-agreement-standards.md +23 -22
  35. package/bundled/locales/zh-CN/core/ai-command-behavior.md +2 -1
  36. package/bundled/locales/zh-CN/core/ai-friendly-architecture.md +311 -72
  37. package/bundled/locales/zh-CN/core/ai-instruction-standards.md +71 -49
  38. package/bundled/locales/zh-CN/core/ai-response-navigation.md +2 -1
  39. package/bundled/locales/zh-CN/core/alerting-standards.md +231 -36
  40. package/bundled/locales/zh-CN/core/anti-hallucination.md +116 -697
  41. package/bundled/locales/zh-CN/core/anti-sycophancy-prompting.md +34 -33
  42. package/bundled/locales/zh-CN/core/api-design-standards.md +144 -58
  43. package/bundled/locales/zh-CN/core/behavior-driven-development.md +2 -1
  44. package/bundled/locales/zh-CN/core/branch-completion.md +75 -20
  45. package/bundled/locales/zh-CN/core/capability-declaration.md +44 -94
  46. package/bundled/locales/zh-CN/core/change-batching-standards.md +2 -1
  47. package/bundled/locales/zh-CN/core/changelog-standards.md +485 -63
  48. package/bundled/locales/zh-CN/core/chaos-engineering-standards.md +141 -39
  49. package/bundled/locales/zh-CN/core/checkin-standards.md +176 -116
  50. package/bundled/locales/zh-CN/core/circuit-breaker.md +43 -77
  51. package/bundled/locales/zh-CN/core/code-review-checklist.md +37 -23
  52. package/bundled/locales/zh-CN/core/commit-message-guide.md +892 -69
  53. package/bundled/locales/zh-CN/core/containerization-standards.md +259 -57
  54. package/bundled/locales/zh-CN/core/context-aware-loading.md +103 -29
  55. package/bundled/locales/zh-CN/core/database-standards.md +115 -114
  56. package/bundled/locales/zh-CN/core/deprecation-standards.md +155 -40
  57. package/bundled/locales/zh-CN/core/design-document-standards.md +265 -55
  58. package/bundled/locales/zh-CN/core/developer-memory.md +150 -60
  59. package/bundled/locales/zh-CN/core/documentation-lifecycle.md +20 -16
  60. package/bundled/locales/zh-CN/core/documentation-structure.md +1284 -127
  61. package/bundled/locales/zh-CN/core/documentation-writing-standards.md +649 -259
  62. package/bundled/locales/zh-CN/core/dual-phase-output.md +37 -70
  63. package/bundled/locales/zh-CN/core/environment-standards.md +251 -73
  64. package/bundled/locales/zh-CN/core/error-code-standards.md +501 -60
  65. package/bundled/locales/zh-CN/core/estimation-standards.md +174 -41
  66. package/bundled/locales/zh-CN/core/execution-history.md +2 -1
  67. package/bundled/locales/zh-CN/core/failure-source-taxonomy.md +71 -84
  68. package/bundled/locales/zh-CN/core/feature-flag-standards.md +202 -57
  69. package/bundled/locales/zh-CN/core/forward-derivation-standards.md +613 -154
  70. package/bundled/locales/zh-CN/core/frontend-design-standards.md +361 -78
  71. package/bundled/locales/zh-CN/core/git-workflow.md +148 -262
  72. package/bundled/locales/zh-CN/core/git-worktree.md +59 -26
  73. package/bundled/locales/zh-CN/core/guides/file-placement-guide.md +132 -48
  74. package/bundled/locales/zh-CN/core/guides/performance-guide.md +61 -59
  75. package/bundled/locales/zh-CN/core/guides/security-guide.md +2 -0
  76. package/bundled/locales/zh-CN/core/health-check-standards.md +46 -104
  77. package/bundled/locales/zh-CN/core/immutability-first.md +83 -60
  78. package/bundled/locales/zh-CN/core/knowledge-transfer-standards.md +94 -31
  79. package/bundled/locales/zh-CN/core/mock-boundary.md +74 -6
  80. package/bundled/locales/zh-CN/core/mutation-testing.md +45 -6
  81. package/bundled/locales/zh-CN/core/observability-standards.md +281 -37
  82. package/bundled/locales/zh-CN/core/performance-standards.md +402 -42
  83. package/bundled/locales/zh-CN/core/pipeline-integration-standards.md +2 -1
  84. package/bundled/locales/zh-CN/core/postmortem-standards.md +358 -53
  85. package/bundled/locales/zh-CN/core/privacy-standards.md +148 -40
  86. package/bundled/locales/zh-CN/core/project-context-memory.md +182 -48
  87. package/bundled/locales/zh-CN/core/project-structure.md +550 -170
  88. package/bundled/locales/zh-CN/core/recovery-recipe-registry.md +54 -114
  89. package/bundled/locales/zh-CN/core/refactoring-standards.md +141 -556
  90. package/bundled/locales/zh-CN/core/requirement-engineering.md +7 -6
  91. package/bundled/locales/zh-CN/core/retrospective-standards.md +215 -22
  92. package/bundled/locales/zh-CN/core/retry-standards.md +46 -101
  93. package/bundled/locales/zh-CN/core/reverse-engineering-standards.md +370 -120
  94. package/bundled/locales/zh-CN/core/runbook-standards.md +294 -48
  95. package/bundled/locales/zh-CN/core/security-decision.md +45 -70
  96. package/bundled/locales/zh-CN/core/security-standards.md +169 -16
  97. package/bundled/locales/zh-CN/core/skill-standard-alignment-check.md +105 -71
  98. package/bundled/locales/zh-CN/core/slo-standards.md +296 -44
  99. package/bundled/locales/zh-CN/core/spec-driven-development.md +37 -6
  100. package/bundled/locales/zh-CN/core/standard-admission-criteria.md +25 -31
  101. package/bundled/locales/zh-CN/core/standard-lifecycle-management.md +49 -57
  102. package/bundled/locales/zh-CN/core/structured-task-definition.md +2 -1
  103. package/bundled/locales/zh-CN/core/supply-chain-security-standards.md +159 -32
  104. package/bundled/locales/zh-CN/core/systematic-debugging.md +87 -42
  105. package/bundled/locales/zh-CN/core/tech-debt-standards.md +202 -86
  106. package/bundled/locales/zh-CN/core/test-completeness-dimensions.md +262 -190
  107. package/bundled/locales/zh-CN/core/test-data-standards.md +252 -30
  108. package/bundled/locales/zh-CN/core/test-driven-development.md +21 -1022
  109. package/bundled/locales/zh-CN/core/test-governance.md +94 -43
  110. package/bundled/locales/zh-CN/core/testing-standards.md +83 -37
  111. package/bundled/locales/zh-CN/core/timeout-standards.md +45 -85
  112. package/bundled/locales/zh-CN/core/token-budget.md +44 -80
  113. package/bundled/locales/zh-CN/core/translation-lifecycle-standards.md +48 -36
  114. package/bundled/locales/zh-CN/core/turn-completion-integrity.md +8 -6
  115. package/bundled/locales/zh-CN/core/verification-evidence.md +44 -22
  116. package/bundled/locales/zh-CN/core/versioning.md +737 -73
  117. package/bundled/locales/zh-CN/core/virtual-organization-standards.md +30 -29
  118. package/bundled/locales/zh-CN/core/workflow-enforcement.md +9 -8
  119. package/bundled/locales/zh-CN/core/workflow-state-protocol.md +9 -8
  120. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +2 -1
  121. package/bundled/locales/zh-CN/docs/CLI-FLOW.md +2 -1
  122. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +19 -10
  123. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +8 -6
  124. package/bundled/locales/zh-CN/docs/STANDARDS-REFERENCE.md +2 -1
  125. package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +133 -132
  126. package/bundled/locales/zh-CN/docs/USER-MANUAL.md +11 -3
  127. package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md +5 -2
  128. package/bundled/locales/zh-CN/docs/specs/system/memory-adoption-strategy.md +2 -0
  129. package/bundled/locales/zh-CN/docs/user/FAQ.md +2 -0
  130. package/bundled/locales/zh-CN/docs/user/GETTING-STARTED.md +2 -0
  131. package/bundled/locales/zh-CN/docs/user/GLOSSARY.md +2 -0
  132. package/bundled/locales/zh-CN/docs/user/README.md +4 -2
  133. package/bundled/locales/zh-CN/docs/user/TROUBLESHOOTING.md +2 -0
  134. package/bundled/locales/zh-CN/integrations/codex/AGENTS.md +136 -2
  135. package/bundled/locales/zh-CN/integrations/codex/README.md +62 -10
  136. package/bundled/locales/zh-CN/integrations/gemini-cli/GEMINI.md +59 -1
  137. package/bundled/locales/zh-CN/integrations/gemini-cli/README.md +9 -2
  138. package/bundled/locales/zh-CN/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md +7 -1
  139. package/bundled/locales/zh-CN/integrations/github-copilot/README.md +8 -2
  140. package/bundled/locales/zh-CN/integrations/github-copilot/copilot-instructions.md +146 -12
  141. package/bundled/locales/zh-CN/integrations/github-copilot/skills-mapping.md +7 -1
  142. package/bundled/locales/zh-CN/integrations/google-antigravity/AGENTS.md +110 -3
  143. package/bundled/locales/zh-CN/integrations/google-antigravity/README.md +7 -1
  144. package/bundled/locales/zh-CN/integrations/opencode/AGENTS.md +140 -2
  145. package/bundled/locales/zh-CN/integrations/opencode/README.md +7 -1
  146. package/bundled/locales/zh-CN/integrations/opencode/skills-mapping.md +8 -2
  147. package/bundled/locales/zh-CN/integrations/openspec/AGENTS.md +46 -1
  148. package/bundled/locales/zh-CN/integrations/openspec/README.md +7 -1
  149. package/bundled/locales/zh-CN/integrations/spec-kit/AGENTS.md +20 -2
  150. package/bundled/locales/zh-CN/integrations/spec-kit/README.md +7 -1
  151. package/bundled/locales/zh-CN/options/changelog/auto-generated.md +2 -0
  152. package/bundled/locales/zh-CN/options/changelog/keep-a-changelog.md +2 -0
  153. package/bundled/locales/zh-CN/options/code-review/automated-review.md +2 -0
  154. package/bundled/locales/zh-CN/options/code-review/pair-programming.md +2 -0
  155. package/bundled/locales/zh-CN/options/commit-message/bilingual.md +139 -50
  156. package/bundled/locales/zh-CN/options/commit-message/english.md +159 -42
  157. package/bundled/locales/zh-CN/options/commit-message/traditional-chinese.md +156 -75
  158. package/bundled/locales/zh-CN/options/documentation/api-docs.md +3 -1
  159. package/bundled/locales/zh-CN/options/documentation/markdown-docs.md +2 -0
  160. package/bundled/locales/zh-CN/options/documentation/wiki-style.md +2 -0
  161. package/bundled/locales/zh-CN/options/git-workflow/gitflow.md +105 -77
  162. package/bundled/locales/zh-CN/options/git-workflow/github-flow.md +75 -57
  163. package/bundled/locales/zh-CN/options/git-workflow/merge-commit.md +155 -44
  164. package/bundled/locales/zh-CN/options/git-workflow/rebase-ff.md +168 -53
  165. package/bundled/locales/zh-CN/options/git-workflow/squash-merge.md +122 -37
  166. package/bundled/locales/zh-CN/options/git-workflow/trunk-based.md +108 -61
  167. package/bundled/locales/zh-CN/options/project-structure/dotnet.md +266 -47
  168. package/bundled/locales/zh-CN/options/project-structure/go.md +301 -43
  169. package/bundled/locales/zh-CN/options/project-structure/java.md +268 -48
  170. package/bundled/locales/zh-CN/options/project-structure/kotlin.md +2 -0
  171. package/bundled/locales/zh-CN/options/project-structure/nodejs.md +168 -51
  172. package/bundled/locales/zh-CN/options/project-structure/php.md +2 -0
  173. package/bundled/locales/zh-CN/options/project-structure/python.md +210 -52
  174. package/bundled/locales/zh-CN/options/project-structure/ruby.md +2 -0
  175. package/bundled/locales/zh-CN/options/project-structure/rust.md +2 -0
  176. package/bundled/locales/zh-CN/options/project-structure/swift.md +2 -0
  177. package/bundled/locales/zh-CN/options/testing/contract-testing.md +2 -0
  178. package/bundled/locales/zh-CN/options/testing/e2e-testing.md +227 -66
  179. package/bundled/locales/zh-CN/options/testing/industry-pyramid.md +2 -0
  180. package/bundled/locales/zh-CN/options/testing/integration-testing.md +185 -73
  181. package/bundled/locales/zh-CN/options/testing/istqb-framework.md +2 -0
  182. package/bundled/locales/zh-CN/options/testing/performance-testing.md +2 -0
  183. package/bundled/locales/zh-CN/options/testing/security-testing.md +2 -0
  184. package/bundled/locales/zh-CN/options/testing/system-testing.md +270 -96
  185. package/bundled/locales/zh-CN/options/testing/unit-testing.md +185 -71
  186. package/bundled/locales/zh-CN/skills/CONTRIBUTING.template.md +43 -42
  187. package/bundled/locales/zh-CN/skills/INTEGRATION-GUIDE.md +2 -1
  188. package/bundled/locales/zh-CN/skills/README.md +2 -1
  189. package/bundled/locales/zh-CN/skills/_shared/README.md +2 -1
  190. package/bundled/locales/zh-CN/skills/adr-assistant/guide.md +240 -4
  191. package/bundled/locales/zh-CN/skills/agents/README.md +180 -82
  192. package/bundled/locales/zh-CN/skills/agents/code-architect.md +3 -1
  193. package/bundled/locales/zh-CN/skills/agents/doc-writer.md +3 -1
  194. package/bundled/locales/zh-CN/skills/agents/reviewer.md +4 -2
  195. package/bundled/locales/zh-CN/skills/agents/spec-analyst.md +3 -1
  196. package/bundled/locales/zh-CN/skills/agents/test-specialist.md +3 -1
  197. package/bundled/locales/zh-CN/skills/ai-collaboration-standards/SKILL.md +91 -81
  198. package/bundled/locales/zh-CN/skills/ai-collaboration-standards/anti-hallucination.md +79 -59
  199. package/bundled/locales/zh-CN/skills/ai-collaboration-standards/certainty-labels.md +66 -40
  200. package/bundled/locales/zh-CN/skills/ai-friendly-architecture/SKILL.md +23 -36
  201. package/bundled/locales/zh-CN/skills/ai-instruction-standards/SKILL.md +217 -137
  202. package/bundled/locales/zh-CN/skills/api-design-assistant/SKILL.md +13 -2
  203. package/bundled/locales/zh-CN/skills/atdd-assistant/SKILL.md +16 -2
  204. package/bundled/locales/zh-CN/skills/atdd-assistant/acceptance-criteria-guide.md +2 -1
  205. package/bundled/locales/zh-CN/skills/atdd-assistant/atdd-workflow.md +98 -1
  206. package/bundled/locales/zh-CN/skills/atdd-assistant/guide.md +148 -132
  207. package/bundled/locales/zh-CN/skills/audit-assistant/SKILL.md +5 -2
  208. package/bundled/locales/zh-CN/skills/bdd-assistant/SKILL.md +16 -2
  209. package/bundled/locales/zh-CN/skills/bdd-assistant/bdd-workflow.md +2 -1
  210. package/bundled/locales/zh-CN/skills/bdd-assistant/gherkin-guide.md +2 -1
  211. package/bundled/locales/zh-CN/skills/bdd-assistant/guide.md +122 -121
  212. package/bundled/locales/zh-CN/skills/changelog-guide/SKILL.md +9 -2
  213. package/bundled/locales/zh-CN/skills/changelog-guide/guide.md +91 -88
  214. package/bundled/locales/zh-CN/skills/checkin-assistant/SKILL.md +12 -2
  215. package/bundled/locales/zh-CN/skills/checkin-assistant/guide.md +211 -210
  216. package/bundled/locales/zh-CN/skills/ci-cd-assistant/SKILL.md +14 -2
  217. package/bundled/locales/zh-CN/skills/code-review-assistant/SKILL.md +12 -2
  218. package/bundled/locales/zh-CN/skills/code-review-assistant/checkin-checklist.md +79 -78
  219. package/bundled/locales/zh-CN/skills/code-review-assistant/guide.md +119 -45
  220. package/bundled/locales/zh-CN/skills/code-review-assistant/review-checklist.md +89 -88
  221. package/bundled/locales/zh-CN/skills/commands/ac-coverage.md +43 -1
  222. package/bundled/locales/zh-CN/skills/commands/api-design.md +2 -1
  223. package/bundled/locales/zh-CN/skills/commands/atdd.md +71 -1
  224. package/bundled/locales/zh-CN/skills/commands/audit.md +2 -1
  225. package/bundled/locales/zh-CN/skills/commands/bdd.md +160 -62
  226. package/bundled/locales/zh-CN/skills/commands/changelog.md +36 -1
  227. package/bundled/locales/zh-CN/skills/commands/check.md +53 -1
  228. package/bundled/locales/zh-CN/skills/commands/checkin.md +45 -1
  229. package/bundled/locales/zh-CN/skills/commands/ci-cd.md +3 -2
  230. package/bundled/locales/zh-CN/skills/commands/code-review.md +41 -1
  231. package/bundled/locales/zh-CN/skills/commands/commit.md +56 -1
  232. package/bundled/locales/zh-CN/skills/commands/config.md +50 -1
  233. package/bundled/locales/zh-CN/skills/commands/coverage.md +43 -1
  234. package/bundled/locales/zh-CN/skills/commands/database.md +4 -3
  235. package/bundled/locales/zh-CN/skills/commands/derive-all.md +42 -1
  236. package/bundled/locales/zh-CN/skills/commands/derive-atdd.md +35 -1
  237. package/bundled/locales/zh-CN/skills/commands/derive-bdd.md +41 -1
  238. package/bundled/locales/zh-CN/skills/commands/derive-tdd.md +42 -1
  239. package/bundled/locales/zh-CN/skills/commands/derive.md +60 -4
  240. package/bundled/locales/zh-CN/skills/commands/dev-workflow.md +58 -8
  241. package/bundled/locales/zh-CN/skills/commands/discover.md +41 -1
  242. package/bundled/locales/zh-CN/skills/commands/docgen.md +37 -1
  243. package/bundled/locales/zh-CN/skills/commands/docs.md +136 -5
  244. package/bundled/locales/zh-CN/skills/commands/durable.md +4 -3
  245. package/bundled/locales/zh-CN/skills/commands/e2e.md +85 -1
  246. package/bundled/locales/zh-CN/skills/commands/guide.md +2 -1
  247. package/bundled/locales/zh-CN/skills/commands/incident.md +5 -4
  248. package/bundled/locales/zh-CN/skills/commands/init.md +57 -1
  249. package/bundled/locales/zh-CN/skills/commands/methodology.md +166 -77
  250. package/bundled/locales/zh-CN/skills/commands/metrics.md +3 -2
  251. package/bundled/locales/zh-CN/skills/commands/migrate.md +5 -4
  252. package/bundled/locales/zh-CN/skills/commands/observability.md +48 -3
  253. package/bundled/locales/zh-CN/skills/commands/pr.md +4 -3
  254. package/bundled/locales/zh-CN/skills/commands/refactor.md +76 -38
  255. package/bundled/locales/zh-CN/skills/commands/release.md +82 -1
  256. package/bundled/locales/zh-CN/skills/commands/requirement.md +40 -1
  257. package/bundled/locales/zh-CN/skills/commands/reverse-bdd.md +36 -1
  258. package/bundled/locales/zh-CN/skills/commands/reverse-sdd.md +44 -1
  259. package/bundled/locales/zh-CN/skills/commands/reverse-tdd.md +42 -1
  260. package/bundled/locales/zh-CN/skills/commands/reverse.md +43 -1
  261. package/bundled/locales/zh-CN/skills/commands/runbook.md +50 -3
  262. package/bundled/locales/zh-CN/skills/commands/scan.md +3 -2
  263. package/bundled/locales/zh-CN/skills/commands/sdd-retro.md +50 -1
  264. package/bundled/locales/zh-CN/skills/commands/sdd.md +182 -1
  265. package/bundled/locales/zh-CN/skills/commands/security.md +3 -2
  266. package/bundled/locales/zh-CN/skills/commands/slo.md +51 -3
  267. package/bundled/locales/zh-CN/skills/commands/tdd.md +74 -5
  268. package/bundled/locales/zh-CN/skills/commands/update.md +70 -8
  269. package/bundled/locales/zh-CN/skills/commit-standards/SKILL.md +4 -4
  270. package/bundled/locales/zh-CN/skills/commit-standards/conventional-commits.md +45 -44
  271. package/bundled/locales/zh-CN/skills/commit-standards/guide.md +172 -52
  272. package/bundled/locales/zh-CN/skills/commit-standards/language-options.md +50 -47
  273. package/bundled/locales/zh-CN/skills/contract-test-assistant/SKILL.md +2 -2
  274. package/bundled/locales/zh-CN/skills/contract-test-assistant/guide.md +76 -1
  275. package/bundled/locales/zh-CN/skills/database-assistant/SKILL.md +18 -5
  276. package/bundled/locales/zh-CN/skills/dev-methodology/SKILL.md +4 -2
  277. package/bundled/locales/zh-CN/skills/dev-methodology/create-methodology.md +2 -0
  278. package/bundled/locales/zh-CN/skills/dev-methodology/runtime.md +2 -0
  279. package/bundled/locales/zh-CN/skills/docs-generator/SKILL.md +16 -2
  280. package/bundled/locales/zh-CN/skills/docs-generator/guide.md +8 -7
  281. package/bundled/locales/zh-CN/skills/documentation-guide/SKILL.md +209 -184
  282. package/bundled/locales/zh-CN/skills/documentation-guide/documentation-structure.md +73 -72
  283. package/bundled/locales/zh-CN/skills/documentation-guide/readme-template.md +37 -36
  284. package/bundled/locales/zh-CN/skills/durable-execution-assistant/SKILL.md +28 -2
  285. package/bundled/locales/zh-CN/skills/e2e-assistant/SKILL.md +21 -6
  286. package/bundled/locales/zh-CN/skills/error-code-guide/SKILL.md +76 -95
  287. package/bundled/locales/zh-CN/skills/git-workflow-guide/SKILL.md +80 -87
  288. package/bundled/locales/zh-CN/skills/git-workflow-guide/branch-naming.md +44 -43
  289. package/bundled/locales/zh-CN/skills/git-workflow-guide/git-workflow.md +66 -65
  290. package/bundled/locales/zh-CN/skills/incident-response-assistant/SKILL.md +31 -13
  291. package/bundled/locales/zh-CN/skills/metrics-dashboard-assistant/SKILL.md +38 -2
  292. package/bundled/locales/zh-CN/skills/observability-assistant/SKILL.md +75 -1
  293. package/bundled/locales/zh-CN/skills/pr-automation-assistant/SKILL.md +32 -6
  294. package/bundled/locales/zh-CN/skills/project-discovery/SKILL.md +8 -2
  295. package/bundled/locales/zh-CN/skills/project-discovery/guide.md +158 -157
  296. package/bundled/locales/zh-CN/skills/project-structure-guide/SKILL.md +49 -46
  297. package/bundled/locales/zh-CN/skills/project-structure-guide/language-patterns.md +8 -7
  298. package/bundled/locales/zh-CN/skills/refactoring-assistant/SKILL.md +22 -2
  299. package/bundled/locales/zh-CN/skills/refactoring-assistant/guide.md +172 -171
  300. package/bundled/locales/zh-CN/skills/release-standards/SKILL.md +66 -23
  301. package/bundled/locales/zh-CN/skills/release-standards/changelog-format.md +42 -41
  302. package/bundled/locales/zh-CN/skills/release-standards/guide.md +51 -43
  303. package/bundled/locales/zh-CN/skills/release-standards/release-workflow.md +131 -95
  304. package/bundled/locales/zh-CN/skills/release-standards/semantic-versioning.md +62 -61
  305. package/bundled/locales/zh-CN/skills/requirement-assistant/SKILL.md +24 -15
  306. package/bundled/locales/zh-CN/skills/requirement-assistant/guide.md +88 -79
  307. package/bundled/locales/zh-CN/skills/requirement-assistant/requirement-checklist.md +128 -127
  308. package/bundled/locales/zh-CN/skills/requirement-assistant/requirement-writing.md +121 -120
  309. package/bundled/locales/zh-CN/skills/retrospective-assistant/guide.md +206 -2
  310. package/bundled/locales/zh-CN/skills/reverse-engineer/SKILL.md +2 -2
  311. package/bundled/locales/zh-CN/skills/reverse-engineer/bdd-extraction.md +2 -1
  312. package/bundled/locales/zh-CN/skills/reverse-engineer/guide.md +297 -173
  313. package/bundled/locales/zh-CN/skills/reverse-engineer/tdd-analysis.md +2 -1
  314. package/bundled/locales/zh-CN/skills/reverse-engineer/workflow.md +2 -1
  315. package/bundled/locales/zh-CN/skills/runbook-assistant/SKILL.md +9 -2
  316. package/bundled/locales/zh-CN/skills/security-assistant/SKILL.md +24 -6
  317. package/bundled/locales/zh-CN/skills/security-scan-assistant/SKILL.md +34 -10
  318. package/bundled/locales/zh-CN/skills/slo-assistant/SKILL.md +2 -1
  319. package/bundled/locales/zh-CN/skills/spec-derivation/SKILL.md +2 -2
  320. package/bundled/locales/zh-CN/skills/spec-driven-dev/guide.md +38 -6
  321. package/bundled/locales/zh-CN/skills/tdd-assistant/SKILL.md +16 -3
  322. package/bundled/locales/zh-CN/skills/tdd-assistant/guide.md +217 -156
  323. package/bundled/locales/zh-CN/skills/tdd-assistant/language-examples.md +727 -82
  324. package/bundled/locales/zh-CN/skills/tdd-assistant/tdd-workflow.md +396 -214
  325. package/bundled/locales/zh-CN/skills/test-coverage-assistant/SKILL.md +14 -5
  326. package/bundled/locales/zh-CN/skills/test-coverage-assistant/guide.md +25 -12
  327. package/bundled/locales/zh-CN/skills/testing-guide/testing-pyramid.md +99 -98
  328. package/bundled/locales/zh-CN/skills/testing-guide/testing-theory.md +3 -1
  329. package/bundled/locales/zh-CN/skills/tools/cline/README.md +2 -1
  330. package/bundled/locales/zh-CN/skills/tools/copilot/README.md +65 -18
  331. package/bundled/locales/zh-CN/skills/tools/copilot/copilot-instructions.md +2 -1
  332. package/bundled/locales/zh-CN/skills/tools/cursor/README.md +2 -1
  333. package/bundled/locales/zh-CN/skills/tools/windsurf/README.md +2 -1
  334. package/bundled/locales/zh-CN/skills/workflows/README.md +4 -2
  335. package/bundled/locales/zh-CN/templates/reverse-spec-template.md +50 -1
  336. package/bundled/locales/zh-TW/CHANGELOG.md +2323 -1128
  337. package/bundled/locales/zh-TW/CLAUDE.md +962 -76
  338. package/bundled/locales/zh-TW/README.md +3 -3
  339. package/bundled/locales/zh-TW/SECURITY.md +4 -3
  340. package/bundled/locales/zh-TW/STANDARDS-MAPPING.md +103 -6
  341. package/bundled/locales/zh-TW/adoption/ADOPTION-GUIDE.md +46 -93
  342. package/bundled/locales/zh-TW/adoption/DAILY-WORKFLOW-GUIDE.md +2 -1
  343. package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +3 -1
  344. package/bundled/locales/zh-TW/adoption/checklists/enterprise.md +10 -9
  345. package/bundled/locales/zh-TW/adoption/checklists/minimal.md +6 -2
  346. package/bundled/locales/zh-TW/adoption/checklists/recommended.md +7 -4
  347. package/bundled/locales/zh-TW/ai/MAINTENANCE.md +34 -14
  348. package/bundled/locales/zh-TW/ai/options/commit-message/traditional-chinese.ai.yaml +48 -40
  349. package/bundled/locales/zh-TW/core/acceptance-criteria-traceability.md +56 -10
  350. package/bundled/locales/zh-TW/core/acceptance-test-driven-development.md +2 -1
  351. package/bundled/locales/zh-TW/core/accessibility-standards.md +895 -46
  352. package/bundled/locales/zh-TW/core/adr-standards.md +2 -1
  353. package/bundled/locales/zh-TW/core/agent-communication-protocol.md +2 -1
  354. package/bundled/locales/zh-TW/core/agent-dispatch.md +102 -33
  355. package/bundled/locales/zh-TW/core/ai-agreement-standards.md +58 -41
  356. package/bundled/locales/zh-TW/core/ai-command-behavior.md +2 -1
  357. package/bundled/locales/zh-TW/core/ai-friendly-architecture.md +306 -67
  358. package/bundled/locales/zh-TW/core/ai-instruction-standards.md +16 -13
  359. package/bundled/locales/zh-TW/core/ai-response-navigation.md +3 -3
  360. package/bundled/locales/zh-TW/core/alerting-standards.md +257 -35
  361. package/bundled/locales/zh-TW/core/anti-hallucination.md +169 -40
  362. package/bundled/locales/zh-TW/core/anti-sycophancy-prompting.md +2 -1
  363. package/bundled/locales/zh-TW/core/api-design-standards.md +2 -1
  364. package/bundled/locales/zh-TW/core/behavior-driven-development.md +3 -17
  365. package/bundled/locales/zh-TW/core/branch-completion.md +130 -34
  366. package/bundled/locales/zh-TW/core/capability-declaration.md +41 -79
  367. package/bundled/locales/zh-TW/core/change-batching-standards.md +2 -1
  368. package/bundled/locales/zh-TW/core/changelog-standards.md +14 -9
  369. package/bundled/locales/zh-TW/core/chaos-engineering-standards.md +138 -36
  370. package/bundled/locales/zh-TW/core/checkin-standards.md +84 -26
  371. package/bundled/locales/zh-TW/core/circuit-breaker.md +48 -87
  372. package/bundled/locales/zh-TW/core/code-review-checklist.md +19 -7
  373. package/bundled/locales/zh-TW/core/commit-message-guide.md +218 -87
  374. package/bundled/locales/zh-TW/core/containerization-standards.md +259 -57
  375. package/bundled/locales/zh-TW/core/context-aware-loading.md +121 -27
  376. package/bundled/locales/zh-TW/core/database-standards.md +2 -1
  377. package/bundled/locales/zh-TW/core/deprecation-standards.md +139 -37
  378. package/bundled/locales/zh-TW/core/design-document-standards.md +265 -55
  379. package/bundled/locales/zh-TW/core/developer-memory.md +102 -12
  380. package/bundled/locales/zh-TW/core/documentation-lifecycle.md +2 -1
  381. package/bundled/locales/zh-TW/core/documentation-structure.md +17 -8
  382. package/bundled/locales/zh-TW/core/dual-phase-output.md +28 -90
  383. package/bundled/locales/zh-TW/core/environment-standards.md +250 -72
  384. package/bundled/locales/zh-TW/core/error-code-standards.md +17 -6
  385. package/bundled/locales/zh-TW/core/estimation-standards.md +177 -44
  386. package/bundled/locales/zh-TW/core/execution-history.md +2 -1
  387. package/bundled/locales/zh-TW/core/failure-source-taxonomy.md +59 -117
  388. package/bundled/locales/zh-TW/core/feature-flag-standards.md +202 -57
  389. package/bundled/locales/zh-TW/core/forward-derivation-standards.md +592 -133
  390. package/bundled/locales/zh-TW/core/frontend-design-standards.md +120 -8
  391. package/bundled/locales/zh-TW/core/git-workflow.md +197 -37
  392. package/bundled/locales/zh-TW/core/git-worktree.md +79 -49
  393. package/bundled/locales/zh-TW/core/guides/anti-hallucination-guide.md +234 -487
  394. package/bundled/locales/zh-TW/core/guides/file-placement-guide.md +86 -2
  395. package/bundled/locales/zh-TW/core/guides/git-workflow-guide.md +411 -464
  396. package/bundled/locales/zh-TW/core/guides/performance-guide.md +2 -0
  397. package/bundled/locales/zh-TW/core/guides/refactoring-guide.md +237 -484
  398. package/bundled/locales/zh-TW/core/guides/security-guide.md +2 -0
  399. package/bundled/locales/zh-TW/core/health-check-standards.md +46 -104
  400. package/bundled/locales/zh-TW/core/immutability-first.md +45 -85
  401. package/bundled/locales/zh-TW/core/knowledge-graph-memory.md +2 -1
  402. package/bundled/locales/zh-TW/core/knowledge-transfer-standards.md +103 -40
  403. package/bundled/locales/zh-TW/core/mock-boundary.md +74 -6
  404. package/bundled/locales/zh-TW/core/observability-standards.md +284 -40
  405. package/bundled/locales/zh-TW/core/performance-standards.md +387 -86
  406. package/bundled/locales/zh-TW/core/pipeline-integration-standards.md +2 -1
  407. package/bundled/locales/zh-TW/core/postmortem-standards.md +367 -36
  408. package/bundled/locales/zh-TW/core/privacy-standards.md +153 -46
  409. package/bundled/locales/zh-TW/core/project-context-memory.md +210 -31
  410. package/bundled/locales/zh-TW/core/project-structure.md +240 -19
  411. package/bundled/locales/zh-TW/core/recovery-recipe-registry.md +54 -114
  412. package/bundled/locales/zh-TW/core/refactoring-standards.md +153 -48
  413. package/bundled/locales/zh-TW/core/requirement-engineering.md +8 -37
  414. package/bundled/locales/zh-TW/core/retrospective-standards.md +127 -7
  415. package/bundled/locales/zh-TW/core/retry-standards.md +41 -105
  416. package/bundled/locales/zh-TW/core/reverse-engineering-standards.md +5 -1
  417. package/bundled/locales/zh-TW/core/runbook-standards.md +296 -23
  418. package/bundled/locales/zh-TW/core/secret-management-standards.md +12 -4
  419. package/bundled/locales/zh-TW/core/security-decision.md +43 -84
  420. package/bundled/locales/zh-TW/core/security-standards.md +204 -25
  421. package/bundled/locales/zh-TW/core/self-review-protocol.md +2 -1
  422. package/bundled/locales/zh-TW/core/skill-standard-alignment-check.md +103 -69
  423. package/bundled/locales/zh-TW/core/slo-standards.md +301 -49
  424. package/bundled/locales/zh-TW/core/spec-driven-development.md +36 -7
  425. package/bundled/locales/zh-TW/core/standard-admission-criteria.md +22 -28
  426. package/bundled/locales/zh-TW/core/standard-lifecycle-management.md +40 -48
  427. package/bundled/locales/zh-TW/core/structured-task-definition.md +2 -1
  428. package/bundled/locales/zh-TW/core/supply-chain-security-standards.md +137 -10
  429. package/bundled/locales/zh-TW/core/systematic-debugging.md +94 -38
  430. package/bundled/locales/zh-TW/core/tech-debt-standards.md +170 -54
  431. package/bundled/locales/zh-TW/core/test-completeness-dimensions.md +101 -12
  432. package/bundled/locales/zh-TW/core/test-data-standards.md +245 -23
  433. package/bundled/locales/zh-TW/core/test-driven-development.md +4 -1
  434. package/bundled/locales/zh-TW/core/test-governance.md +92 -32
  435. package/bundled/locales/zh-TW/core/testing-standards.md +61 -14
  436. package/bundled/locales/zh-TW/core/timeout-standards.md +45 -85
  437. package/bundled/locales/zh-TW/core/token-budget.md +41 -112
  438. package/bundled/locales/zh-TW/core/translation-lifecycle-standards.md +28 -16
  439. package/bundled/locales/zh-TW/core/turn-completion-integrity.md +8 -6
  440. package/bundled/locales/zh-TW/core/verification-evidence.md +2 -1
  441. package/bundled/locales/zh-TW/core/versioning.md +6 -2
  442. package/bundled/locales/zh-TW/core/virtual-organization-standards.md +42 -36
  443. package/bundled/locales/zh-TW/core/workflow-enforcement.md +2 -1
  444. package/bundled/locales/zh-TW/core/workflow-state-protocol.md +2 -1
  445. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +2 -1
  446. package/bundled/locales/zh-TW/docs/CLI-FLOW.md +2 -1
  447. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +12 -3
  448. package/bundled/locales/zh-TW/docs/DEV-WORKFLOW-MAPPING.md +2 -1
  449. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +8 -6
  450. package/bundled/locales/zh-TW/docs/STANDARDS-REFERENCE.md +2 -1
  451. package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +2 -1
  452. package/bundled/locales/zh-TW/docs/USER-MANUAL.md +9 -1
  453. package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md +4 -1
  454. package/bundled/locales/zh-TW/docs/specs/system/memory-adoption-strategy.md +2 -0
  455. package/bundled/locales/zh-TW/docs/user/FAQ.md +2 -0
  456. package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md +2 -0
  457. package/bundled/locales/zh-TW/docs/user/GLOSSARY.md +2 -0
  458. package/bundled/locales/zh-TW/docs/user/README.md +2 -0
  459. package/bundled/locales/zh-TW/docs/user/TROUBLESHOOTING.md +2 -0
  460. package/bundled/locales/zh-TW/integrations/claude-code/README.md +2 -1
  461. package/bundled/locales/zh-TW/integrations/codex/AGENTS.md +136 -2
  462. package/bundled/locales/zh-TW/integrations/codex/README.md +7 -1
  463. package/bundled/locales/zh-TW/integrations/gemini-cli/GEMINI.md +59 -1
  464. package/bundled/locales/zh-TW/integrations/gemini-cli/README.md +8 -1
  465. package/bundled/locales/zh-TW/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md +7 -1
  466. package/bundled/locales/zh-TW/integrations/github-copilot/README.md +9 -3
  467. package/bundled/locales/zh-TW/integrations/github-copilot/copilot-instructions.md +146 -12
  468. package/bundled/locales/zh-TW/integrations/github-copilot/skills-mapping.md +7 -1
  469. package/bundled/locales/zh-TW/integrations/google-antigravity/AGENTS.md +110 -3
  470. package/bundled/locales/zh-TW/integrations/google-antigravity/README.md +7 -1
  471. package/bundled/locales/zh-TW/integrations/opencode/AGENTS.md +140 -2
  472. package/bundled/locales/zh-TW/integrations/opencode/README.md +7 -1
  473. package/bundled/locales/zh-TW/integrations/opencode/skills-mapping.md +8 -2
  474. package/bundled/locales/zh-TW/integrations/openspec/AGENTS.md +46 -1
  475. package/bundled/locales/zh-TW/integrations/openspec/README.md +7 -1
  476. package/bundled/locales/zh-TW/integrations/spec-kit/AGENTS.md +20 -2
  477. package/bundled/locales/zh-TW/integrations/spec-kit/README.md +7 -1
  478. package/bundled/locales/zh-TW/methodologies/guides/tdd-guide.md +584 -475
  479. package/bundled/locales/zh-TW/options/changelog/auto-generated.md +2 -0
  480. package/bundled/locales/zh-TW/options/changelog/keep-a-changelog.md +2 -0
  481. package/bundled/locales/zh-TW/options/code-review/automated-review.md +2 -0
  482. package/bundled/locales/zh-TW/options/code-review/pair-programming.md +2 -0
  483. package/bundled/locales/zh-TW/options/commit-message/bilingual.md +93 -5
  484. package/bundled/locales/zh-TW/options/commit-message/english.md +118 -1
  485. package/bundled/locales/zh-TW/options/commit-message/traditional-chinese.md +82 -1
  486. package/bundled/locales/zh-TW/options/documentation/api-docs.md +2 -0
  487. package/bundled/locales/zh-TW/options/documentation/markdown-docs.md +2 -0
  488. package/bundled/locales/zh-TW/options/documentation/wiki-style.md +2 -0
  489. package/bundled/locales/zh-TW/options/git-workflow/gitflow.md +99 -71
  490. package/bundled/locales/zh-TW/options/git-workflow/github-flow.md +68 -50
  491. package/bundled/locales/zh-TW/options/git-workflow/merge-commit.md +131 -20
  492. package/bundled/locales/zh-TW/options/git-workflow/rebase-ff.md +142 -27
  493. package/bundled/locales/zh-TW/options/git-workflow/squash-merge.md +100 -15
  494. package/bundled/locales/zh-TW/options/git-workflow/trunk-based.md +103 -56
  495. package/bundled/locales/zh-TW/options/project-structure/dotnet.md +233 -14
  496. package/bundled/locales/zh-TW/options/project-structure/go.md +270 -12
  497. package/bundled/locales/zh-TW/options/project-structure/java.md +235 -15
  498. package/bundled/locales/zh-TW/options/project-structure/kotlin.md +2 -0
  499. package/bundled/locales/zh-TW/options/project-structure/nodejs.md +136 -19
  500. package/bundled/locales/zh-TW/options/project-structure/php.md +2 -0
  501. package/bundled/locales/zh-TW/options/project-structure/python.md +177 -19
  502. package/bundled/locales/zh-TW/options/project-structure/ruby.md +2 -0
  503. package/bundled/locales/zh-TW/options/project-structure/rust.md +2 -0
  504. package/bundled/locales/zh-TW/options/project-structure/swift.md +2 -0
  505. package/bundled/locales/zh-TW/options/testing/contract-testing.md +2 -0
  506. package/bundled/locales/zh-TW/options/testing/e2e-testing.md +182 -21
  507. package/bundled/locales/zh-TW/options/testing/industry-pyramid.md +2 -0
  508. package/bundled/locales/zh-TW/options/testing/integration-testing.md +134 -22
  509. package/bundled/locales/zh-TW/options/testing/istqb-framework.md +2 -0
  510. package/bundled/locales/zh-TW/options/testing/performance-testing.md +2 -0
  511. package/bundled/locales/zh-TW/options/testing/security-testing.md +2 -0
  512. package/bundled/locales/zh-TW/options/testing/system-testing.md +175 -1
  513. package/bundled/locales/zh-TW/options/testing/unit-testing.md +123 -9
  514. package/bundled/locales/zh-TW/skills/CONTRIBUTING.template.md +3 -2
  515. package/bundled/locales/zh-TW/skills/INTEGRATION-GUIDE.md +2 -1
  516. package/bundled/locales/zh-TW/skills/README.md +2 -1
  517. package/bundled/locales/zh-TW/skills/_shared/README.md +2 -1
  518. package/bundled/locales/zh-TW/skills/ac-coverage/SKILL.md +15 -4
  519. package/bundled/locales/zh-TW/skills/adr-assistant/guide.md +123 -3
  520. package/bundled/locales/zh-TW/skills/agents/README.md +99 -1
  521. package/bundled/locales/zh-TW/skills/agents/code-architect.md +2 -0
  522. package/bundled/locales/zh-TW/skills/agents/doc-writer.md +2 -0
  523. package/bundled/locales/zh-TW/skills/agents/reviewer.md +3 -1
  524. package/bundled/locales/zh-TW/skills/agents/spec-analyst.md +2 -0
  525. package/bundled/locales/zh-TW/skills/agents/test-specialist.md +2 -0
  526. package/bundled/locales/zh-TW/skills/ai-collaboration-standards/SKILL.md +48 -37
  527. package/bundled/locales/zh-TW/skills/ai-collaboration-standards/anti-hallucination.md +22 -2
  528. package/bundled/locales/zh-TW/skills/ai-collaboration-standards/certainty-labels.md +29 -3
  529. package/bundled/locales/zh-TW/skills/ai-friendly-architecture/SKILL.md +23 -36
  530. package/bundled/locales/zh-TW/skills/ai-instruction-standards/SKILL.md +12 -36
  531. package/bundled/locales/zh-TW/skills/api-design-assistant/SKILL.md +21 -5
  532. package/bundled/locales/zh-TW/skills/atdd-assistant/SKILL.md +40 -15
  533. package/bundled/locales/zh-TW/skills/atdd-assistant/acceptance-criteria-guide.md +2 -1
  534. package/bundled/locales/zh-TW/skills/atdd-assistant/atdd-workflow.md +98 -1
  535. package/bundled/locales/zh-TW/skills/atdd-assistant/guide.md +24 -8
  536. package/bundled/locales/zh-TW/skills/audit-assistant/SKILL.md +8 -2
  537. package/bundled/locales/zh-TW/skills/bdd-assistant/SKILL.md +29 -6
  538. package/bundled/locales/zh-TW/skills/bdd-assistant/bdd-workflow.md +2 -1
  539. package/bundled/locales/zh-TW/skills/bdd-assistant/gherkin-guide.md +2 -1
  540. package/bundled/locales/zh-TW/skills/bdd-assistant/guide.md +9 -8
  541. package/bundled/locales/zh-TW/skills/changelog-guide/SKILL.md +12 -3
  542. package/bundled/locales/zh-TW/skills/changelog-guide/guide.md +11 -7
  543. package/bundled/locales/zh-TW/skills/checkin-assistant/SKILL.md +19 -3
  544. package/bundled/locales/zh-TW/skills/checkin-assistant/guide.md +5 -3
  545. package/bundled/locales/zh-TW/skills/ci-cd-assistant/SKILL.md +35 -16
  546. package/bundled/locales/zh-TW/skills/code-review-assistant/SKILL.md +19 -2
  547. package/bundled/locales/zh-TW/skills/code-review-assistant/checkin-checklist.md +2 -1
  548. package/bundled/locales/zh-TW/skills/code-review-assistant/guide.md +81 -6
  549. package/bundled/locales/zh-TW/skills/code-review-assistant/review-checklist.md +2 -1
  550. package/bundled/locales/zh-TW/skills/commands/ac-coverage.md +47 -2
  551. package/bundled/locales/zh-TW/skills/commands/api-design.md +3 -2
  552. package/bundled/locales/zh-TW/skills/commands/atdd.md +80 -10
  553. package/bundled/locales/zh-TW/skills/commands/audit.md +3 -2
  554. package/bundled/locales/zh-TW/skills/commands/bdd.md +114 -16
  555. package/bundled/locales/zh-TW/skills/commands/changelog.md +45 -9
  556. package/bundled/locales/zh-TW/skills/commands/check.md +74 -21
  557. package/bundled/locales/zh-TW/skills/commands/checkin.md +56 -11
  558. package/bundled/locales/zh-TW/skills/commands/ci-cd.md +2 -1
  559. package/bundled/locales/zh-TW/skills/commands/code-review.md +43 -2
  560. package/bundled/locales/zh-TW/skills/commands/commit.md +58 -4
  561. package/bundled/locales/zh-TW/skills/commands/config.md +52 -4
  562. package/bundled/locales/zh-TW/skills/commands/coverage.md +45 -4
  563. package/bundled/locales/zh-TW/skills/commands/database.md +3 -2
  564. package/bundled/locales/zh-TW/skills/commands/derive-all.md +44 -2
  565. package/bundled/locales/zh-TW/skills/commands/derive-atdd.md +37 -2
  566. package/bundled/locales/zh-TW/skills/commands/derive-bdd.md +44 -3
  567. package/bundled/locales/zh-TW/skills/commands/derive-tdd.md +45 -3
  568. package/bundled/locales/zh-TW/skills/commands/derive.md +62 -5
  569. package/bundled/locales/zh-TW/skills/commands/dev-workflow.md +60 -9
  570. package/bundled/locales/zh-TW/skills/commands/discover.md +43 -2
  571. package/bundled/locales/zh-TW/skills/commands/docgen.md +39 -2
  572. package/bundled/locales/zh-TW/skills/commands/docs.md +139 -7
  573. package/bundled/locales/zh-TW/skills/commands/durable.md +3 -2
  574. package/bundled/locales/zh-TW/skills/commands/e2e.md +86 -3
  575. package/bundled/locales/zh-TW/skills/commands/guide.md +4 -2
  576. package/bundled/locales/zh-TW/skills/commands/incident.md +3 -2
  577. package/bundled/locales/zh-TW/skills/commands/init.md +72 -15
  578. package/bundled/locales/zh-TW/skills/commands/methodology.md +117 -28
  579. package/bundled/locales/zh-TW/skills/commands/metrics.md +2 -1
  580. package/bundled/locales/zh-TW/skills/commands/migrate.md +2 -1
  581. package/bundled/locales/zh-TW/skills/commands/observability.md +45 -2
  582. package/bundled/locales/zh-TW/skills/commands/pr.md +2 -1
  583. package/bundled/locales/zh-TW/skills/commands/refactor.md +54 -13
  584. package/bundled/locales/zh-TW/skills/commands/release.md +83 -2
  585. package/bundled/locales/zh-TW/skills/commands/requirement.md +41 -2
  586. package/bundled/locales/zh-TW/skills/commands/reverse-bdd.md +37 -2
  587. package/bundled/locales/zh-TW/skills/commands/reverse-sdd.md +45 -2
  588. package/bundled/locales/zh-TW/skills/commands/reverse-tdd.md +43 -2
  589. package/bundled/locales/zh-TW/skills/commands/reverse.md +44 -2
  590. package/bundled/locales/zh-TW/skills/commands/runbook.md +47 -2
  591. package/bundled/locales/zh-TW/skills/commands/scan.md +3 -2
  592. package/bundled/locales/zh-TW/skills/commands/sdd-retro.md +52 -3
  593. package/bundled/locales/zh-TW/skills/commands/sdd.md +209 -28
  594. package/bundled/locales/zh-TW/skills/commands/security.md +3 -2
  595. package/bundled/locales/zh-TW/skills/commands/slo.md +48 -2
  596. package/bundled/locales/zh-TW/skills/commands/tdd.md +71 -2
  597. package/bundled/locales/zh-TW/skills/commands/update.md +64 -2
  598. package/bundled/locales/zh-TW/skills/commit-standards/SKILL.md +2 -2
  599. package/bundled/locales/zh-TW/skills/commit-standards/conventional-commits.md +2 -1
  600. package/bundled/locales/zh-TW/skills/commit-standards/guide.md +137 -17
  601. package/bundled/locales/zh-TW/skills/commit-standards/language-options.md +21 -18
  602. package/bundled/locales/zh-TW/skills/contract-test-assistant/SKILL.md +2 -2
  603. package/bundled/locales/zh-TW/skills/contract-test-assistant/guide.md +81 -1
  604. package/bundled/locales/zh-TW/skills/database-assistant/SKILL.md +21 -5
  605. package/bundled/locales/zh-TW/skills/deploy-assistant/SKILL.md +2 -1
  606. package/bundled/locales/zh-TW/skills/dev-methodology/SKILL.md +4 -1
  607. package/bundled/locales/zh-TW/skills/dev-methodology/create-methodology.md +2 -0
  608. package/bundled/locales/zh-TW/skills/dev-methodology/runtime.md +2 -0
  609. package/bundled/locales/zh-TW/skills/docs-generator/SKILL.md +19 -2
  610. package/bundled/locales/zh-TW/skills/docs-generator/guide.md +4 -3
  611. package/bundled/locales/zh-TW/skills/documentation-guide/SKILL.md +67 -42
  612. package/bundled/locales/zh-TW/skills/documentation-guide/documentation-structure.md +2 -1
  613. package/bundled/locales/zh-TW/skills/documentation-guide/readme-template.md +2 -1
  614. package/bundled/locales/zh-TW/skills/durable-execution-assistant/SKILL.md +32 -3
  615. package/bundled/locales/zh-TW/skills/e2e-assistant/SKILL.md +25 -7
  616. package/bundled/locales/zh-TW/skills/error-code-guide/SKILL.md +17 -34
  617. package/bundled/locales/zh-TW/skills/git-workflow-guide/SKILL.md +33 -38
  618. package/bundled/locales/zh-TW/skills/git-workflow-guide/branch-naming.md +2 -1
  619. package/bundled/locales/zh-TW/skills/git-workflow-guide/git-workflow.md +2 -1
  620. package/bundled/locales/zh-TW/skills/incident-response-assistant/SKILL.md +35 -14
  621. package/bundled/locales/zh-TW/skills/journey-test-assistant/SKILL.md +2 -14
  622. package/bundled/locales/zh-TW/skills/knowledge-graph/SKILL.md +6 -2
  623. package/bundled/locales/zh-TW/skills/metrics-dashboard-assistant/SKILL.md +42 -3
  624. package/bundled/locales/zh-TW/skills/observability-assistant/SKILL.md +85 -18
  625. package/bundled/locales/zh-TW/skills/pr-automation-assistant/SKILL.md +27 -3
  626. package/bundled/locales/zh-TW/skills/project-discovery/SKILL.md +11 -3
  627. package/bundled/locales/zh-TW/skills/project-discovery/guide.md +5 -3
  628. package/bundled/locales/zh-TW/skills/project-discovery/workflow.md +2 -1
  629. package/bundled/locales/zh-TW/skills/project-structure-guide/SKILL.md +19 -16
  630. package/bundled/locales/zh-TW/skills/project-structure-guide/language-patterns.md +2 -1
  631. package/bundled/locales/zh-TW/skills/refactoring-assistant/SKILL.md +26 -3
  632. package/bundled/locales/zh-TW/skills/refactoring-assistant/guide.md +4 -2
  633. package/bundled/locales/zh-TW/skills/release-standards/SKILL.md +91 -45
  634. package/bundled/locales/zh-TW/skills/release-standards/changelog-format.md +4 -3
  635. package/bundled/locales/zh-TW/skills/release-standards/guide.md +14 -5
  636. package/bundled/locales/zh-TW/skills/release-standards/release-workflow.md +5 -1
  637. package/bundled/locales/zh-TW/skills/release-standards/semantic-versioning.md +2 -1
  638. package/bundled/locales/zh-TW/skills/requirement-assistant/SKILL.md +15 -6
  639. package/bundled/locales/zh-TW/skills/requirement-assistant/guide.md +18 -8
  640. package/bundled/locales/zh-TW/skills/requirement-assistant/requirement-checklist.md +2 -1
  641. package/bundled/locales/zh-TW/skills/requirement-assistant/requirement-writing.md +2 -1
  642. package/bundled/locales/zh-TW/skills/retrospective-assistant/guide.md +200 -6
  643. package/bundled/locales/zh-TW/skills/reverse-engineer/bdd-extraction.md +2 -1
  644. package/bundled/locales/zh-TW/skills/reverse-engineer/guide.md +161 -36
  645. package/bundled/locales/zh-TW/skills/reverse-engineer/tdd-analysis.md +2 -1
  646. package/bundled/locales/zh-TW/skills/reverse-engineer/workflow.md +2 -1
  647. package/bundled/locales/zh-TW/skills/runbook-assistant/SKILL.md +9 -1
  648. package/bundled/locales/zh-TW/skills/security-assistant/SKILL.md +25 -5
  649. package/bundled/locales/zh-TW/skills/security-scan-assistant/SKILL.md +34 -8
  650. package/bundled/locales/zh-TW/skills/skill-builder/SKILL.md +3 -21
  651. package/bundled/locales/zh-TW/skills/slo-assistant/SKILL.md +3 -1
  652. package/bundled/locales/zh-TW/skills/spec-derivation/SKILL.md +2 -1
  653. package/bundled/locales/zh-TW/skills/spec-driven-dev/guide.md +35 -2
  654. package/bundled/locales/zh-TW/skills/sweep/SKILL.md +2 -1
  655. package/bundled/locales/zh-TW/skills/tdd-assistant/SKILL.md +10 -2
  656. package/bundled/locales/zh-TW/skills/tdd-assistant/guide.md +68 -9
  657. package/bundled/locales/zh-TW/skills/tdd-assistant/language-examples.md +693 -47
  658. package/bundled/locales/zh-TW/skills/tdd-assistant/tdd-workflow.md +183 -1
  659. package/bundled/locales/zh-TW/skills/test-coverage-assistant/SKILL.md +15 -5
  660. package/bundled/locales/zh-TW/skills/test-coverage-assistant/guide.md +26 -13
  661. package/bundled/locales/zh-TW/skills/testing-guide/testing-pyramid.md +2 -1
  662. package/bundled/locales/zh-TW/skills/testing-guide/testing-theory.md +3 -1
  663. package/bundled/locales/zh-TW/skills/tools/cline/README.md +2 -1
  664. package/bundled/locales/zh-TW/skills/tools/copilot/README.md +65 -18
  665. package/bundled/locales/zh-TW/skills/tools/copilot/copilot-instructions.md +2 -1
  666. package/bundled/locales/zh-TW/skills/tools/cursor/README.md +2 -1
  667. package/bundled/locales/zh-TW/skills/tools/windsurf/README.md +2 -1
  668. package/bundled/locales/zh-TW/skills/workflows/README.md +11 -9
  669. package/bundled/locales/zh-TW/templates/reverse-spec-template.md +50 -1
  670. package/bundled/skills/.claude-plugin/plugin.json +71 -0
  671. package/bundled/skills/commit-standards/SKILL.md +2 -2
  672. package/bundled/skills/commit-standards/guide.md +3 -2
  673. package/bundled/skills/commit-standards/language-options.md +19 -17
  674. package/package.json +2 -2
  675. package/src/commands/audit.js +28 -1
  676. package/src/commands/check.js +72 -3
  677. package/src/commands/compile.js +37 -4
  678. package/src/commands/config.js +49 -24
  679. package/src/commands/init.js +78 -30
  680. package/src/commands/open-work.js +6 -2
  681. package/src/commands/release-messages.js +228 -0
  682. package/src/commands/release.js +127 -68
  683. package/src/commands/run-intent.js +11 -0
  684. package/src/commands/spec.js +4 -2
  685. package/src/commands/update.js +227 -47
  686. package/src/compilers/claude-code-compiler.js +9 -1
  687. package/src/config/ai-agent-paths.js +14 -1
  688. package/src/core/installed-formats.js +15 -0
  689. package/src/core/open-work-config.js +20 -1
  690. package/src/core/project-config.js +55 -0
  691. package/src/i18n/messages.js +106 -2
  692. package/src/installers/hooks-installer.js +1 -1
  693. package/src/installers/manifest-installer.js +1 -1
  694. package/src/installers/skills-installer.js +1 -1
  695. package/src/installers/standards-installer.js +3 -1
  696. package/src/mcp/server.js +9 -3
  697. package/src/prompts/init.js +26 -22
  698. package/src/reconciler/actual-state-scanner.js +2 -8
  699. package/src/reconciler/backup-locations.js +5 -0
  700. package/src/reconciler/backup-manager.js +19 -11
  701. package/src/reconciler/desired-state-calculator.js +89 -57
  702. package/src/reconciler/plan-executor.js +101 -8
  703. package/src/reconciler/recorded-versions.js +49 -0
  704. package/src/reconciler/relative-path.js +23 -0
  705. package/src/uninstallers/hook-uninstaller.js +9 -1
  706. package/src/uninstallers/skills-uninstaller.js +22 -3
  707. package/src/utils/available-standards-report.js +25 -4
  708. package/src/utils/available-standards.js +13 -3
  709. package/src/utils/build-manifest.js +1 -1
  710. package/src/utils/commit-message-judge.js +60 -13
  711. package/src/utils/friction-detector.js +23 -11
  712. package/src/utils/git-hooks.js +106 -4
  713. package/src/utils/integration-generator.js +95 -67
  714. package/src/utils/legacy-hook-migration.js +121 -2
  715. package/src/utils/open-work-tracking.mjs +105 -16
  716. package/src/utils/sdd-header.js +16 -4
  717. package/src/utils/skills-installer.js +2 -1
  718. package/src/utils/spinner.js +14 -4
  719. package/src/utils/standard-validator.js +3 -2
  720. package/standards-registry.json +10 -8
  721. 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-03-17
5
+ last_synced: 2026-10-16
6
+ source_hash: 9d2d83e23aef
6
7
  status: current
7
8
  ---
8
9
 
9
- # 文件撰写规范
10
+ # 文档编写规范
10
11
 
11
- > [English](../../../core/documentation-writing-standards.md) | **繁体中文**
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
- | 设计决策 | 关键决策的理由(或连结至 ADR) | 建议 |
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
- **用途**: 记录对外 API 界面
233
+ **用途**: 记录外部 API 接口
198
234
 
199
235
  **必要章节**:
200
236
 
201
237
  | 章节 | 说明 | 必要性 |
202
238
  |---------|-------------|----------|
203
- | API 概述 | 版本、Base URL、认证方式 | 必要 |
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 | 资料库主机 | `192.168.1.100` |
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
- | 向后相容 | API/资料库相容性说明 | 必要 |
354
- | 集成方通知 | 需通知的外部系统 | 如适用 |
389
+ | 向后兼容性 | API/数据库兼容性说明 | 必要 |
390
+ | 集成方通知 | 需要通知的外部系统 | 如适用 |
355
391
 
356
392
  ---
357
393
 
@@ -361,32 +397,79 @@ status: current
361
397
 
362
398
  **用途**: 记录重要的架构决策及其理由
363
399
 
364
- **档案命名**: `NNN-kebab-case-title.md`(例如:`001-use-postgresql.md`)
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
- 1. 方案 A - 因...而拒绝
403
- 2. 方案 B - 因...而拒绝
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
- project-root/
445
- ├── README.md # 专案入口文件
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
- ## AI 协作文档
559
+ ## Quick Start
560
+ [Minimal steps to get started]
478
561
 
479
- ### Token 感知设计
562
+ ## API Reference
563
+ [Detailed API documentation]
480
564
 
481
- 为 AI 助手优化文档结构:
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
- **AI 友好文档模式**:
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
- # YAML 前置元数据(AI 可解析)
497
- title: API 端点文档
498
- version: 2.0.0
499
- last_updated: 2026-01-24
500
- ai_summary: 用户认证 API,支持 OAuth2
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
- <!-- AI-SECTION-START: quick-reference -->
504
- ## 快速参考
505
- [最常用的信息放这里]
506
- <!-- AI-SECTION-END: quick-reference -->
635
+ 这些元数据字段有助于检索系统按相关性对文档进行排序和筛选。
507
636
 
508
- <!-- AI-SECTION-START: details -->
509
- ## 详细说明
510
- [完整详情放这里]
511
- <!-- AI-SECTION-END: details -->
512
- ```
637
+ ### 为 AI 代码生成编写文档
638
+
639
+ 当文档将用于生成代码时:
513
640
 
514
- ### 为 AI 代码生成撰写
641
+ **包含明确约束**:
515
642
 
516
- 撰写 AI 可用于生成代码的文档:
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
- **范例 - 好的 AI 提示友好文档**:
653
+ **明确错误场景**:
519
654
 
520
655
  ```markdown
521
- ## 创建用户 API
656
+ ## Error Responses
522
657
 
523
- ### 约束条件
524
- - 用户名:3-20 字符,仅字母数字
525
- - 邮箱:必须唯一
526
- - 密码:最少 8 字符,需含数字
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
- - 409: 邮箱已存在
533
- - 400: 验证失败
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
- **AI 提示友好特点**:
678
+ ### AI 提示词集成
679
+
680
+ 对于定义 AI 辅助工作流的文档:
681
+
682
+ **嵌入式提示词模板**:
683
+
684
+ ```markdown
685
+ ## AI Code Review Prompt
537
686
 
538
- | 特点 | 好处 |
539
- |------|------|
540
- | 明确约束条件 | AI 可生成验证代码 |
541
- | 列出错误情况 | AI 可生成错误处理 |
542
- | 结构化格式 | AI 易于解析 |
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: 示例 API
554
- version: 1.0.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 规范(异步 API)
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: 事件 API
768
+ title: Order Events
589
769
  version: 1.0.0
590
-
591
770
  channels:
592
- user/created:
771
+ orders/created:
593
772
  publish:
594
- summary: 用户创建事件
595
773
  message:
596
- payload:
597
- type: object
598
- properties:
599
- userId:
600
- type: string
601
- createdAt:
602
- type: string
603
- format: date-time
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 年级阅读程度 | 避免:「utilize」→ 使用:「use」 |
615
- | **图片替代文字** | 为所有非装饰性图片提供描述性替代文字 | `![显示三层架构的架构图](path/to/arch.png)` |
616
- | **标题层级** | 使用正确的标题层级(h1→h2→h3),不跳级 | 不要从 `#` 直接跳到 `###` |
617
- | **链接文字** | 使用描述性链接文字,而非「点此」 | 避免:[点此] → 使用:[安装指南] |
618
- | **代码区块** | 使用带语言标示的围栏式代码区块 | ` ```javascript ` 而非 ` ``` ` |
619
- | **色彩独立性** | 不仅依赖色彩传达意义 | 搭配使用 ✅/❌ 图标与色彩 |
1001
+ |-------------|-------------|---------|
1002
+ | **浅显语言** | 使用清晰、简单的语言;目标为 8 年级阅读水平 | 避免:“utilize” → 使用:“use” |
1003
+ | **图片替代文字** | 为所有非装饰性图片提供描述性替代文字 | `![Architecture diagram showing three-tier layout](path/to/arch.png)` |
1004
+ | **标题层级** | 使用正确的标题层级(h1→h2→h3),切勿跳级 | 不要从 `#` 直接跳到 `###` |
1005
+ | **链接文字** | 使用描述性链接文字,而非“点击此处” | 避免:[click here] → 使用:[installation guide] |
1006
+ | **代码块** | 使用带语言标识符的围栏式代码块 | ` ```javascript ` 而非 ` ``` ` |
1007
+ | **色彩独立性** | 不要仅依赖色彩传达意义 | 在色彩旁搭配使用 ✅/❌ 图标 |
620
1008
 
621
1009
  ---
622
1010
 
623
1011
  ## 相关标准
624
1012
 
625
- - [Documentation Structure Standard](documentation-structure.md) - 文件结构标准
626
- - [Changelog Standards](changelog-standards.md) - 变更日志标准
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.1.0 | 2026-01-24 | 新增:AI 协作文档章节、API 文档标准(OpenAPI 3.1、AsyncAPI 2.6) |
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/) 授权发布。