XeroBis/website

规划与文档化

为什么

像“移植卡片”或“为作品集添加标签”这类请求听起来像是最终决定，但通常隐藏着未解决的抉择：现在应该构建多少、哪些内容要从旧仓库保留或修改或删除、哪个 Schema 拥有数据、什么应该放入 @shared。立即开始构建可能导致做错事情、返工、或者背离 documentation/decisions.md 中已记录的选择。先提问可以让文档——进而让代码——准确地反映用户真正想要的记录。

何时适用

任何会改变 documentation/ 所追踪内容的请求：功能或面向用户的行为、Schema/表/列/业务规则、技术或库的选择、文件夹/架构结构、或者 migration-plan.md 中的步骤。小型、完全确定的修改（修复此拼写错误、将此标签重命名为精确的 X）无需面试环节——请根据实际情况判断哪些内容确实存在歧义。

步骤

1. 在提问前先阅读。 浏览与请求相关的 documentation/*.md 部分的文档（以及相关代码）。在移植时，还需阅读旧仓库自身的文档（../<repo>/documentation/、../<repo>/CLAUDE.md）以及被移植的代码。不要询问文档已给出答案的内容。以它们作为你提问的基线。

2. 使用 AskUserQuestion 提出澄清性问题。 倾向于多个小而具体的问题，而非一个宽泛的问题。此仓库中合适的提问目标包括：

   • 现在构建多少 vs. 以后构建多少；
   • 移植时：从旧应用中保留哪些内容、修改哪些内容、丢弃哪些内容（旧行为并非自动想要的）；
   • 新表属于哪个 Schema（应用自身的 schema，或者如果每个应用都需要，则属于 core）；
   • 某个部分属于一个应用，还是属于 @shared / 共享的后端模块；
   • features.md 需要记录的 UX 细节以及新数据的形状。

   为每个问题提供一个建议的默认值，以便用户快速决策。

3. 严格尊重用户给出的范围。 如果他们将其限定为“仅文档”或“只做 X，不做 Y”，不要悄悄做更多事情——在后续扩展范围之前再次确认。

4. 在做出决策的同一步骤中更新文档，路由规则遵循 CLAUDE.md 中的表格：

   • 文件夹结构、环境、端口、请求流程 → architecture.md
   • Schema、表、列、关系、业务规则 → data-model.md，放在该 Schema 的子节下
   • 技术/库/架构选择 → decisions.md：一个带日期的条目，说明选择了什么、放弃了什么以及原因，与该文件的风格保持一致
   • 面向用户的行为、验证规则 → features.md，放在该应用的子节下
   • 任何推迟、排除或仍仅作为可能性的事项 → ideas.md
   • 移植进度 → migration-plan.md 状态列
   • 生产运行手册变更 → deployment.md

5. 将已解决的构想移出 ideas.md。 如果某个变更将 ideas.md 中的条目变为实际决策，请删除或重写该条目，而不是留下过时的重复内容。