AI 开发规范与约定

apps/desktop 负责 Tauri + React 界面，apps/server 负责本机服务和任务，packages/contracts 负责共享协议。接下来还差一个实际问题：我们怎样让每次参与开发的 AI 都记得这些约定？

如果每次对话都重新解释目录、密钥和消息状态，AI 很容易在下一次任务里忘掉其中一条。我们需要把长期有效的规则放进仓库，把某一次架构决定记录下来，再把重复的工作方法整理成可以按需加载的 Skill。这样，Vibe Coding 就不只是不断发送提示词，而是让项目逐渐拥有自己的工作手册。

本篇只建立这套约定，不安装 Skill，不接通模型，也不实现一个通用插件平台。后续开始做功能时，AI 才有一份稳定的参考。

把规则、设计和方法分别保存

项目的工作手册不必是一份很长的文档。先区分每种内容解决什么问题，后续新增约定时才知道应该放在哪里。

AGENTS.md 是项目规则。 它应该回答“在这个仓库里修改代码时，什么边界始终成立”，例如客户端不能读取 API Key、服务端不能反过来依赖 React、聊天消息只能有一个事实来源。它不适合记录一次临时讨论，也不适合复制整个项目说明书。

docs/architecture.md 和 docs/decisions/ 解释取舍。 前者可以概括当前结构，后者用一条简短记录说明“为什么选择本机 Node 服务”“为什么暂时不引入第二个运行时”。当未来决定改变边界时，留下这条记录，AI 和人都能知道旧代码为什么存在。

docs/failures/ 只记录已经发生、而且值得避免的失败。 例如，如果曾经出现把工作区标识当成磁盘路径，或者把流式消息同时放进 assistant-ui 和 Zustand 的问题，就可以在确认原因后记录。内容应包含现象、原因、修复方式和以后如何识别，不能变成每天都要阅读的长日志。这些是记录方式的示例，不表示当前项目已经发生过这些故障。

检查脚本属于可执行的护栏。 它可以检查目录是否从错误的方向导入、敏感文件是否被提交，或者协议类型是否仍能被两个应用编译。规则写在文档里，脚本负责把容易忘的部分变成证据。当前不需要一次写完所有检查；出现重复错误后再补一条最小检查即可。涉及数据、安全或公共协议的改动，则应在本次就安排对应验证，不必等到重复出错。

这些路径是一种组织约定，并不表示当前仓库已经具备全部文件。项目已有根目录规则、模块 README 和消息渲染等专题文档时，应优先接到已有位置，不必为了套用表格先生成一批空目录。模块的使用方法继续写在 README，按需的工作步骤则交给后文的 Skills。

例如，项目规则可以要求“配置读取失败时保留原文件”；设计说明解释为什么不能自动重置；回归检查则构造损坏文件，观察程序是否拒绝覆盖。三者互相配合，文档本身不能证明程序已经满足要求。

AGENTS.md：让每次修改沿用同一组规则

AGENTS.md 是给开发助手阅读的项目说明。它应该包含当前仓库的重要约束，让新任务能够沿用已有做法，而不是每次从聊天记录中重新寻找。

不同开发工具支持的文件和加载范围并不完全相同，使用前需要核对所用工具。GitHub Copilot 的官方文档就区分了仓库级、路径级和 Agent 指令，不能把某一种加载方式视为所有工具的通用行为。

规则要写成能够判断的要求。“保持高质量”不容易检查；“保存失败保留输入，不显示成功”则能直接对应用户操作。稳定边界放在根文件，设置模块的详细组织方式继续指向它自己的 README。

对这个工作台，值得固定下来的主要有三类要求。

首先是职责归属：界面通过接口请求数据，服务和运行时处理实际任务，共享协议不混入应用实现。其次是状态与数据：assistant-ui 管理聊天输入和消息，保存成功需要等待服务确认，读取失败不能覆盖原文件。最后是权限与修改范围：保留路径检查，不泄露密钥，不为一个局部功能顺手重构无关模块。

这些要求都能对应具体后果。例如，服务保存失败，界面却提前显示新名称，用户就会误以为修改已生效；另建一份聊天消息状态，则会增加停止和切换会话时的同步工作。规则应该说明怎样避免这些问题，而不是只要求 AI“认真开发”。

下面是一份可以对照现有规则精简采用的中文示例。本篇只在文章中展示，不覆盖应用已有的 AGENTS.md：

# AI 工作台开发约定

## 修改前先阅读

- 阅读根目录规则、目标模块 README 和相关源码，先确认已有能力。
- 查看 Git 状态，保留用户和其他任务的未提交修改。
- 沿用现有包管理器、锁文件和依赖版本，不顺手升级无关依赖。

## 目录与职责

- apps/desktop 负责桌面窗口、界面与用户交互。
- apps/server 负责本机接口、配置和数据组装。
- packages/agent-runtime 负责项目聊天与工具注册。
- packages/host-runtime 负责文件操作和路径保护。
- packages/contracts 只放共享协议、类型和校验。
- 运行时包不反向依赖应用，公共 UI 不依赖桌面业务。

## 界面与状态

- 复用公共 UI、现有主题及 Animate UI，不逐页复制控件。
- 聊天沿用 assistant-ui，不另外复制消息和草稿状态。
- 保留键盘操作、焦点恢复、窄窗口和减少动态效果支持。
- 新增界面文案同时维护简体中文和英文词条。

## 数据与权限

- 服务确认写入成功后，界面才能提示保存成功。
- 保存失败保留输入；配置读取失败不得用默认值覆盖原文件。
- 服务根据项目标识解析关联目录，保留路径和敏感文件检查。
- 文件修改保留先读后改、版本冲突检测及取消处理。
- 密钥不得进入客户端响应、日志、聊天或 Git。

## 任务与交付

- 一次完成一个明确目标，不混入无关重构和批量格式化。
- 检查和服务启动遵循当前仓库的授权约定。
- 说明行为变化、实际验证结果、失败项和未验证部分。
- 未经要求，不提交、推送、部署或发布。

这份示例保留的是反复影响修改的约束。一次重命名任务的临时文件清单、个人电脑路径或真实密钥，都不应成为永久规则。

如果任务要求、项目规范和 Skill 出现矛盾，应指出具体冲突及影响，依据当前工具的指令规则处理。涉及权限、数据兼容或无法确定的取舍时，再请用户决定，不能默默删掉约束来完成任务。

Skills：把重复的方法按需交给 AI

AGENTS.md 回答“在这里必须遵守什么”，Skill 回答“遇到这一类任务时怎样做”。例如，项目要求运行时不能反向依赖应用；架构检查 Skill 则指导 AI 找出本次修改的导入关系，判断有没有越过这条边界。

Skill 通常以 SKILL.md 为入口，包含用途、触发条件和工作步骤，也可以附参考材料或脚本。使用时应确认开发工具支持的目录与加载方式，并阅读实际内容。文件被放进仓库，不代表工具一定会自动识别；其中的脚本也不会因为被推荐就获得执行授权。

下面是一份简体中文的教学示例。目录位置由所用开发工具确定，示例中的名称用于识别技能，正文说明工作方法：

---
name: workbench-boundary-review
description: 为 AI 工作台新增功能或调整模块职责前，检查依赖、状态和权限边界。
---

# 工作台边界检查

1. 阅读 AGENTS.md、目标模块 README 和相关入口，确认当前实现。
2. 列出本次用户动作经过的界面、服务、协议和运行时。
3. 说明数据由谁保存，状态由谁管理，是否新增文件访问能力。
4. 检查是否重复实现已有组件、聊天状态或任务执行入口。
5. 给出最小修改范围，以及能验证用户行为的检查办法。
6. 对无法确认的权限或兼容性问题说明依据，不自行放宽限制。

这个 Skill 帮助 AI 在改动前应用已有约定，不另建一套项目规则。只有涉及模块职责、状态或权限变化时才需要这类检查；调整一句按钮文字，不必做完整架构评审。

还要区分开发助手的 Skill 与工作台将来可能支持的用户扩展。前者帮助 AI 修改代码，后者需要应用自己的加载、权限和生命周期机制。把 SKILL.md 复制进应用，不能自动获得可安全执行的插件能力。

值得参考的公开 Skill

我们不需要把所有公开 Skill 都装进项目。选择标准是：它是否解决当前反复出现的问题，能否在不改变现有技术栈的前提下提供方法，输出是否容易被人检查。

下面七项包含技能和阅读资料。各项用途依据原始说明核对，使用边界则结合当前工作台确定；本篇只介绍选择方法，不安装或执行这些技能。

这张表表达的是适用范围，不是热度排名。Architecture Designer 适合在架构变化前梳理约束和取舍，但一次表单调整不需要生成微服务拓扑；shadcn/ui Skill 可以帮助组合按钮与表单，也不应借此重新生成 assistant-ui 的消息区。

选用时可以从当前问题逐项判断：

• 组件越来越难改：同一个设置组件靠大量开关参数区分用途时，优先参考 Composition Patterns，检查组件组合与状态归属。
• 已有功能变慢：先找到重复渲染或加载问题，再用 React Best Practices 对照适用规则，不凭感觉给全部组件增加缓存。
• 同一种错误反复出现：用 Harness Engineering 整理原因，补上一条可以发现回归的检查，并记录对应证据。
• 需要重新认识已有工程：用 Architecture Blueprint Generator 提取边界和调用关系，逐项核对它引用的文件，不要求它替尚不存在的功能生成完整架构。

引入 Skill 前，还要阅读它准备调用的工具、命令和附带脚本。比如 shadcn/ui Skill 可能运行配置发现命令，Harness Engineering 可能建议新增检查；这些动作仍受当前仓库的执行授权与修改范围约束。一个技能被推荐，不代表它可以覆盖项目规则。

规则冲突时，先说明影响再继续

一次任务可能同时涉及用户要求、仓库根目录规则、模块规范和当前加载的 Skill。它们的读取范围与优先关系，应以开发工具的实际说明为准，不把某一种工具的机制写成通用标准。

发现冲突时，应明确指出哪两项要求不同，以及会影响什么。例如，某个技能建议自动运行完整构建，而仓库要求先取得执行授权，就应保留该执行边界，报告待验证事项。若用户已经明确授权，则按当前有效要求执行，不重复询问。

项目规则应保持简短，方便人和 AI 找到具体条目。权限、数据兼容或范围无法确定时再请用户决定；不能为了完成任务，默默扩大目录访问范围或跳过数据保护。

每次只推进一个能检查的用户动作

有了长期约定，可以先让 AI 做一次只读检查，确认它对当前实现和修改范围的理解：

先阅读当前工作台的 AGENTS.md、项目模块 README 和相关入口。
只读检查项目重命名功能，列出界面、服务和共享协议的相关文件。
说明已有行为、缺少的部分，以及是否影响文件夹关联和聊天归属。
本轮不修改文件，不启动服务，也不运行验证命令。

只读检查给出的是后续修改的依据，不是功能已经完成的证据。如果归属不清或需要改变权限，应先澄清；范围明确后，再交给 AI 一个能检查结果的任务：

检查并完善已有项目的重命名入口，不重复实现已经具备的能力。

先阅读 AGENTS.md、项目模块、共享协议和保存逻辑，确认现有能力。
复用已有菜单、表单和公共 UI，只修改与重命名有关的部分。
保存成功后更新名称；失败保留输入并允许重试。
保持项目 ID、文件夹关联和已有聊天不变，同时补充中英文文案。

先说明现有行为和本次需要补齐的部分，再完成实现。验证遵循当前仓库授权约定，
交付时区分实际执行的检查与未验证项，不提交或推送代码。

这个目标可以沿用户动作检查：打开菜单、修改名称、保存、看到新名称，并确认原来的聊天仍归属于同一项目。失败路径则检查错误是否可见、输入是否保留。它比“全面优化项目管理”更容易确定完成条件，也更容易定位回归。

验证方式要与变更相称：数据格式改动要看双方是否一致；保存逻辑要检查失败与恢复；界面操作要看焦点、禁用和反馈。类型检查可以发现部分接口错误，却不能独自证明“保存失败保留输入”这样的用户行为。

当前桌面仓库还明确要求：运行开发服务、构建、测试、格式化、解析校验和浏览器验收，需要用户当前消息的明确授权。这里是项目自己的执行约定，并非所有项目通用。没有执行授权时，可以先完成源码和差异审查，如实交付待验证项，不能把未运行的检查写成通过。

让约定随着项目更新

任务完成后，先判断这次发现是否值得长期保留。只是某个页面的实现细节，就放在模块代码与说明中；改变了数据归属或服务边界，就更新设计记录；确实发生过、容易复发的问题，再补充具体规则或检查。

下一次任务开始时，AI 读取的是更新后的约定，人也能据此检查修改范围和结果。项目规则保持简短，设计决定有依据，Skills 按需要参与，这份工作手册才能随着工作台一起维护下去。