和 Agent 一起开发时，你需要说明希望用户完成什么、有哪些业务限制，以及怎样判断完成。Agent 负责结合项目约定找到相关代码、实现改动并验证结果。你不必先知道应该调用哪个内部 API，才能把需求说清楚。
本篇面向已经创建好的应用。如果还没有项目，先阅读创建应用。这里的 Agent 指帮助你编写应用代码的 Coding Agent；应用内供业务用户使用的 Agents 是另一项能力。
让 Agent 在正确的项目中工作
在应用根目录启动 Agent，让它可以读取源码、package.json、AGENTS.md 和 .agents/。继续已有项目时，说明当前工作目录和已有功能，避免它另建一个应用。
开始时可以这样说：
请在当前应用中继续开发。先阅读项目的 AGENTS.md，并按这次任务查阅相关 Skills。
先了解现有实现和未提交的修改，保留已有功能与我的改动。
如果已有插件或组件能满足需求，优先使用它们。这段话用于建立工作上下文，不需要在每次小修改时完整重复。涉及部署、数据库变更或账号操作时，还要明确目标环境及允许操作的范围。
AGENTS.md 与 Skills 各自做什么
应用会把开发约定放在项目中，Agent 应按当前安装版本读取，而不是套用其他版本或其他项目的规则。
| 位置 | 内容 | 怎样维护 |
|---|---|---|
AGENTS.md |
应用开发的入口规则，以及进一步阅读的索引 | 随应用维护，保持简短 |
.agents/rules/ |
这个应用特有的结构、业务约定与定制说明 | 修改应用约定时同步更新，并从 AGENTS.md 链接 |
.agents/skills/ |
依赖包和插件提供的开发、升级、部署及能力使用指引 | 根据已安装依赖同步，不直接修改生成副本 |
当前模板的 postinstall 会同步 Skills。如果安装时跳过了脚本，或同步目录缺失，可以在应用根目录运行：
pnpm nocobase skills sync日常功能开发从 nocobase-app-development 开始，按任务读取相关参考文件；使用插件能力时再查阅该插件的 Skill。升级 Core 和部署应用分别有自己的指引，不要用开发环境启动步骤替代生产部署。
应用规则写在应用里，共享规则随包维护。 例如，你决定所有业务日期都按某个时区解释，应记录在 .agents/rules/。不要只把约定留在一次聊天里，也不要直接修改下次同步就会被替换的 .agents/skills/ 文件。
用业务语言描述需求
一份可执行的需求通常回答五个问题：
| 要说明的内容 | 示例 |
|---|---|
| 谁在什么地方使用 | 团队成员在任务列表里查看和修改任务 |
| 希望完成什么 | 新建任务时可以选择一位负责人，也可以暂不分配 |
| 规则和边界 | 只能选启用的现有用户；旧任务和现有权限保持不变 |
| 失败时怎么办 | 负责人已停用时保留任务标题，提示重新选择 |
| 怎样判断完成 | 保存后刷新仍能看到负责人；没有权限时界面和接口都拒绝操作 |
不确定的业务决定应直接指出。例如“旧任务是否需要统一分配负责人还没确定”，而不是让 Agent 猜一个默认用户。文件位置、组件名称和内部方法则可以由它从项目指引中查找。
一个可以直接使用的需求
下面的请求适用于已有任务列表和新建功能、尚未加入负责人功能的应用：
请给现有任务应用增加负责人。
新建任务时可以选择一位启用的现有用户，也可以暂不分配。
任务列表要显示负责人；没有负责人时显示“未分配”。
旧任务继续保留，不自动替它们指定负责人，也不改变任何用户的角色和权限。
如果选择的用户在保存前已经停用，保留我填好的标题，提示重新选择。
保存成功后，刷新页面仍能看到正确的负责人。
沿用当前应用的界面风格，并提供中英文文案。
请按项目指引实现，使用独立测试数据验证新建、未分配、停用用户和无权限的情况。
这一轮不做任务转交、通知或“我的任务”。
完成后告诉我改了什么、验证了什么，以及还有哪些情况没有验证。这里描述的是用户能理解的行为。具体字段、关联、权限策略和选择器用法，交给 Agent 按应用约定处理。需要固定的接口合同或已有设计时，可以把对应文档一并提供；无需把全部实现细节重新抄进提示词。
把较大的需求分成可验证的改动
“做一个完整项目管理系统”包含太多尚未决定的业务问题。可以先完成一个小而闭合的结果，再扩展下一项能力。
例如为任务增加项目归属，可以按下面的范围推进：
- 数据层：项目与任务的关系、旧任务保留方式、关联约束，先用数据库测试验证。
- 业务接口：查询和新建项目、修改任务归属，验证输入和两边的数据权限。
- 页面交互：项目列表、新建弹窗和任务项目选择，验证加载、保存、失败和键盘操作。
每一步都说明当前范围和完成条件。只完成数据层时，应明确页面还不能操作；不能把“迁移测试通过”表述成“用户已经可以管理项目”。需要快速完成一个小功能时，也可以一次交付这些部分，无需为每个文件分别发起任务。
检查实现是否符合需求
先检查可观察的行为，再确认改动是否符合项目约定。你可以要求 Agent 提供简短的改动说明，并指出相关文件，重点回答：
- 旧数据和原有功能是否保留，数据结构变化是否使用了新的迁移。
- 页面访问、业务操作和数据范围是否分别处理，是否意外给用户增加了权限。
- 是否使用现有插件和组件，是否改动了超出需求的布局、主题或其他功能。
- 字段错误是否显示在对应输入旁，保存失败后是否保留输入。
- 新增接口是否进入应用 API 文档，中英文文案是否齐全。
不要仅凭一张成功截图判断功能已经完成。隐藏按钮不代表接口拒绝越权，显示成功提示也不代表数据库确实保存了数据。
验证真实结果
让 Agent 把自动检查与实际操作的结果分开报告。验证范围应覆盖本次改动及受影响的已有行为，避免把无关的全量检查当成每次修改的固定步骤。
| 验证层次 | 要确认什么 |
|---|---|
| 静态检查 | 修改的代码符合项目格式、类型与约定 |
| 数据库与接口测试 | 使用隔离数据检查持久化、迁移、校验、授权及失败后的数据状态 |
| 页面与组件测试 | 检查表单、加载、反馈和用户输入行为 |
| 浏览器操作 | 在实际应用中完成操作、刷新验证，并用普通用户检查权限 |
能用真实应用、数据库和权限服务验证的业务规则，就直接验证。只有外部传输或测试环境缺少浏览器能力等必要边界才使用替身，并说明替代了什么；不要 mock 正在验证的业务行为。
浏览器验证应使用应用实际打印的完整入口地址和专门的测试账号。数据库测试应使用隔离数据，不能为了跑通测试清空当前应用的业务数据。详细的任务示例见搭建第一个应用。
发现问题时，可以给出复现路径和预期结果，而不是只说“不对”：
用只读成员登录后，任务列表没有“新建”按钮，但直接提交新建请求仍然成功。
预期是只读成员既不能在页面新建，也不能通过接口新建。
请检查服务端授权，修复后用同一普通账号验证，并确认管理员仍然可以新建。如果 Agent 没有环境或账号验证某一步，应说明缺少什么、已经验证到哪里；不能用“代码看起来没问题”代替实际验证结果。
完成后留下什么
一次改动结束时，应留下可检查的代码和验证记录。让 Agent 简要说明改动、已通过的检查、未验证项，以及启动或查看结果的方法。应用特有的新约定写入 .agents/rules/，业务代码和测试一起维护。
提交代码、发布版本和部署到具体环境是不同动作。根据这次任务约定执行；本地测试通过并不意味着已经部署。需要上线时，继续阅读选择部署方式。
如果选择手动开发，同一套数据、接口、页面和验收约定仍然适用。各专题的“不使用 Agent”部分提供对应的代码与操作步骤。