architecture

架构

必读： ../pack-shared/standards.md。规则位于 AGENTS.md 的 Taste 和 Architecture 部分。本技能包含审计步骤和示例。即使未调用本技能，也不要跳过这些规则。

提问风格： ../pack-shared/asking.md

起草结构卡之前，先应用 AGENTS.md 的 Taste 和 Architecture 部分。这些部分中的标题就是引用键。使用共享的 执行上下文。

按照 ../pack-shared/subagents.md，通过 Task 子代理进行查找：非简单的同级／服务／文件夹搜索必须使用 explorer Tasks（主代理不执行 grep）；独立工作流必须并行运行（每个工作流一个 Task，数量不限于两个）。你负责审查这些结果并据此编写结构卡，然后在后续简报中注入摘录。仅当全新项目的结构简单到无需探索代码库时才跳过 Tasks。没有 architect worker。

如果父级已提供预期结果、完成条件、非目标、已锁定的决策、Active Rules、当前切片和工作流，则沿用该简报。

流程

1. 探索。 优先复用或扩展现有服务，而不是另建并行服务；如果某个基础组件已经能完成这一项工作，就复用它。若工作流中的现有结构不合适，应指出问题，而不是照搬。记录：
   • 处理相同关注点（计费、身份验证等）的现有服务：优先复用／扩展
   • 这些服务／深层模块中的现有基础组件：如果已经能完成特定工作就复用；不要另建分支
   • 工作流中不合适的现有结构（按功能拆分的领域逻辑、不合适的同级结构、放置不当的文件）：不要照搬；仅在当前范围要求时，规划保持行为不变的迁移
   • 类似功能如何调用这些服务（仅通过公共 API？）
   • 现有入口模式（services、hooks、classes 还是 modules）
   • 命名和导入风格
   • 同级模块是在写入时存储汇总数据，还是在读取时重新计算（优先前者）
   • 同级模块如何在公共写入操作中检查身份和所有权（复用该 helper；不要另建并行的授权路径）
   • 列表／查询路径是否有索引和分页，以及查询是否保持确定性
2. 在聊天中，根据 Architecture 部分起草 Structure 卡（始终适用／涉及写入时／涉及列表时／大型功能）。需要保持行为不变的迁移，必须在开始编写功能代码之前列出。
3. 在内联执行上下文中附上适用的卡。不要创建或更新计划、工作区、登记表或其他由 Agent 管理的产物。若结构决策尚未确定，发起一轮 /grill-me Questions 提问（遵循 ../pack-shared/asking.md）。
4. 根据卡片实施。 先创建所属文件夹，再创建其中的文件（architecture:folders）。不要在包含无关文件的混合父目录（src/、app/、convex/ 或已有无关文件的路由文件夹）中添加新文件。先完成迁移／纠正，再在旧结构上叠加新的功能代码。领域逻辑放在服务中；功能只能调用公共函数。通过在服务中使用基础组件构建深度。由服务在公共写入操作中强制检查身份和所有权。保持查询具有确定性；验证公共参数（taste:types-tell-the-truth）。添加新的环境变量名之前，按用途盘点现有变量（taste:reuse-env）。
5. 对于实现中途出现的结构蔓延、重复的领域逻辑、分叉的基础组件或先前的错误：只有当前验收标准、Active Rules 或具名发现要求时才迁移；否则，在所属文件夹中保留最精简直接的结构，并在聊天中记录后续事项。准备添加混合的同级模块？将它嵌套起来即可。这不算额外流程。
6. 完成前，按照 Architecture 部分执行自检。

如果父级已有后续步骤的负责人

将结构决策交给父级的内联上下文和 Worker Brief， 然后，面向用户的 UI 使用 /design，非 UI 使用 /implement。将所需修正反馈给父级。

如果这是用户的一次性需求

• 结构卡片已获批准 → /task
• 规模问题、重复服务、分叉原语、遗漏操作、混合父级 文件转储、环境变量同义词（SITE_URL 已存在时使用 FRONTEND_URL），或缺少 写入路径权限 → 验收证据 / /code-review