Team based Instructions

Brief

对在软件交付过程中已经积极使用 AI 的团队来说，下一步要做的不只是依赖个人的临时提示（prompt），而是要为整个软件团队建立一套经过策划的共享指令体系。
这种实践可以帮助你把 AI 有效应用到所有交付任务中——不仅仅是写代码——通过共享那些已经被验证过的、高质量的指令来实现。

最直接的落地方式，就是在项目代码仓库中提交专门的指令文件，比如新建一个 $$AGENTS.md$$。
目前大多数 AI 编码工具——包括 Cursor、Windsurf 和 Claude Code——都支持通过自定义斜杠命令（slash commands）或工作流（workflows）来共享这些指令。

对于非编码类任务，你可以在组织层面建立统一的提示词（prompt）库，让团队随时调用。
这种系统化的方式可以实现持续改进：一旦某条提示被优化，整个团队就都能立刻受益，并且始终都能访问到当前最优的 AI 使用指令。

来源：技术雷达

Guide

1. 为什么需要“团队级指令”，而不是只靠个人 prompt？

如果只依赖个人经验，每个人在用 AI 时都会：

• 自己摸索一套提示语，“效果只在自己头上生效”
• 新同事要从零开始学习如何跟 AI 协作
• 同一个问题，不同人问法不同，效果差异大，难以复现

而“策划并共享指令”（curated shared instructions）的目标是：

• 把“用 AI 做这类任务的最佳问法”固化下来
• 每个成员都能一键复用，不需要重新踩坑
• 项目级别的“使用 AI 方式”变得标准、可复用、可改进

可以理解为：给 AI 建一本“团队操作手册”，而不是靠每个人即兴发挥。

2. $$AGENTS.md$$ 可以写什么？

一个典型的 $$AGENTS.md$$ 文件，可以长这样（示例结构）：

1. 全局原则（For all agents）
   • 代码风格（缩进、命名规则、语言版本等）
   • 安全与合规要求（比如不得引入 GPL 代码、不得上传隐私数据）
   • 输出格式要求（是否必须带测试用例、是否必须解释关键设计决策）
2. 按角色划分的 AI 代理（Agents）
   • Code Reviewer Agent：
     • 任务：代码审查
     • 输入：PR diff / 关键文件列表
     • 要求：必须检查哪些问题（性能、安全、边界条件、文档注释等）
     • 输出模板：先总体结论，再按文件列出问题，再给出建议修改方案
   • Refactoring Agent：
     • 任务：重构老代码
     • 指令：保持对外行为不变；优先消除重复逻辑；建议拆分函数；给出重构后结构说明
   • Spec Writer Agent：
     • 任务：根据产品需求写技术设计说明 / 接口规格文档
   • Test Writer Agent：
     • 任务：为给定代码编写单元测试 / 集成测试用例
   • …可根据团队情况扩展
3. 常用 prompt 模板
   • “请帮我评审这段代码，重点关注性能和安全：…”
   • “请根据以下用户故事，输出技术设计文档模板：…”
   • “请基于下面 API 代码，生成接口文档（OpenAPI/Markdown）：…”
4. 使用指南
   • 在 Cursor/Windsurf/Claude Code 中如何调用这些指令
   • 推荐工作流：
     • 写完功能 → 调用 Test Writer 生成测试 → 调用 Reviewer 审查
   • 注意事项：哪些任务必须人工复核，哪些可以完全交给 AI

3. 如何在工具里落地共享指令？

以几类常见工具为例（思路，不依赖具体实现细节）：

1. Cursor / Windsurf / Claude Code 里
   • 利用“自定义 Slash 命令”功能，比如：
     • $$/review$$ → 自动调用 Code Reviewer 模板
     • $$/tests$$ → 使用 Test Writer 模板
     • $$/refactor$$ → 使用 Refactoring Agent 模板
   • 把这些命令及其含义写进 $$AGENTS.md$$，保证团队共识。
2. 非编码任务（产品、设计、运营等）
   • 在公司知识库（如 Confluence、Notion、飞书文档）建立
     “Prompt Library” 或 “AI 使用手册” 页面：
     • 产品需求分析模板
     • 用户访谈纪要整理模板
     • PRD 规范模板
     • 市场调研 / 竞品分析的结构化问题清单
   • 把这些模板复制-粘贴到任意 AI 工具即可使用，不依赖具体 IDE。
3. 通过版本控制实现“持续改进”
   • $$AGENTS.md$$ 放在代码仓库，和源码一起版本管理
   • 团队成员可以通过 PR 改进这些指令（就像改代码一样）
   • 变更记录可追踪，讨论也可在 Review 中完成
   • “最优 prompt”不再是某个人脑子里的经验，而是团队资产

4. 建设这套体系时的实用建议

1. 从高频场景入手，不要一开始做得太大
   • 先选 2–3 个最常见、最耗时的场景：
     • 代码审查
     • 编写测试
     • 阅读和总结 legacy 代码
   • 先把这几类的 prompt 固化到 $$AGENTS.md$$，再逐步扩展。
2. 为每条指令加上“适用范围 + 示例”
   • 每个 Agent 或模板下，加一段：
     • 什么时候用？
     • 输入示例
     • 输出示例（缩略版即可）
   • 让新人看一眼就知道怎么用。
3. 明确“AI 能做什么 + 必须人工把关什么”
   • 比如：
     • AI 可以起草代码 / 文档，但安全相关逻辑必须人工复查
     • 合同、法律文本必须由法律同事最终审阅
   • 在 $$AGENTS.md$$ 或 Prompt Library 顶部写清楚，避免滥用 AI。
4. 定期“回顾和升级”指令
   • 每 1–2 个月开一个轻量的“AI 使用回顾”
     • 哪些 prompt 真有用？
     • 哪些场景 AI 表现不好，需要改写指令？
   • 把会议输出直接转化为对 $$AGENTS.md$$ 和 Prompt Library 的修改。