用编码代理构建

初学者演练

先决条件：阅读下面两篇入门指南并完成 Mobile 本地安装。编码代理是一种 AI 工具——Cursor、Claude Code、Devin 或类似助手——它读取您的项目、编辑文件并运行命令。本页内容适用于您使用的任意一种。

速查术语：提示词（prompt）是你粘给代理的指令文本。diff 是它提出的文件变更清单。存储库根目录是包含 package.json 的最顶层文件夹——代理应始终从这里开始。

1. 在存储库根目录打开 .agents/skills/，复制与您任务最接近的技能——add-a-mobile-screen 是不错的第一选择。

2. 把它粘贴给代理并描述您的改动，然后加一行：在动代码之前先读 llms.txt，再读 AGENTS.md，再读 .ai/PROJECT_CONTEXT.md。

3. 让代理在动手前先列出它将改动的文件和将运行的检查。完成后审查 diff——你是在批准对产品的真实改动。

4. 发布、提交商店和付费提供商调用永远不属于任务提示词。把它们保留为您明确批准的单独步骤。

• 开始之前
• 终端基础知识
• 手机本地设置

你的代理要读的文件

存储库附带一小摞专为代理而写的文件，不只给人看。你永远不需要手工粘贴这些上下文——把代理指向 llms.txt，剩下的它自己会读。

阅读顺序很重要：llms.txt 是地图，AGENTS.md 划定边界，.ai/PROJECT_CONTEXT.md 承载此前会话的经验。跳过边界的代理会写出你无法交付的代码。

附带的技能

.agents/skills/ 下的每个文件都是一份完整的简报：把它粘贴给代理或让代理自行阅读，套件的规则会随之传递——服务器优先的数据、包内无密钥、离线仅作为网络错误的回退。

可粘贴的 prompts/ 库只在 Web 存储库中附带；此 checkout 改为附带技能。若要无人值守地完成安装，请使用 agent-setup 指南中的现成提示词。

• 让代理执行安装

• add-a-mobile-screen——新增或修改界面及其数据流和离线行为
• adding-a-dependency——安全地添加、升级或移动 npm 依赖
• reviewing-a-pr——审查 diff 的正确性、工作区隔离和密钥
• upgrading-from-upstream——把更新版本的套件拉入您的应用
• verify-changes——在交接前选择并运行正确的检查
• writing-unit-tests——用 Vitest 覆盖新逻辑

代理如何在会话之间记忆

代理在会话之间没有记忆——.ai/ 文件夹就是记忆。.ai/PROJECT_CONTEXT.md 记录最近的改动及原因。旁边的镜像文档，如 .ai/apps/mobile/src/ideas/index.md，解释了 apps/mobile/src/ideas/index.ts 背后单凭代码看不出的决策。

契约很简单：改文件前先读它的镜像，改动落地时更新镜像。Open Threads 条目记录未完成的工作，让下次会话接着做而不是从头再来。过期的镜像比没有更糟——审查代理的 diff 时，检查被改文件的镜像是否随之更新。

诚实地审查代理的工作

完成的任务要看证据而不是总结。在保留代理的工作成果前，用 docs/agent-security.md 检查部署的方式来检查它：

哪里不对就把 diff 退回去——你点出失败的检查时，代理修自己的活最快。对于它本不该擅自尝试的事，明确说一次就够；此后整个会话边界都成立。

• 验证关卡与测试套件

• 它声称跑过的测试真的跑了——要命令和输出，而不是结论。
• 机密仍只在服务端——新内容里没有 NEXT_PUBLIC_ 或 EXPO_PUBLIC_ 前缀，也没有密钥被打印进报告或提交。
• 每一次用户数据的读写都保持 workspaceId 作用域——没有任何查询信任浏览器发来的 id。
• 每个被改文件的 .ai/ 镜像随代码一起更新。
• 发布、部署和付费提供商调用仍是你批准的独立步骤——代理从未自行合并、推送或部署。
• 某一步失败两次时，它停下来报告失败的命令，而不是绕过去自行发挥。