Skip to main content

2 posts tagged with "AI"

View All Tags

· 7 min read
Chris (Gentle) Yang

在 AI 编程普及的今天，GitHub Copilot、Cursor、OpenAI Codex等工具已经成为开发者的标配。当有新的贡献者带着 AI 编程工具来到你的开源项目时，AI 是会成为一个高效的高级工程师，还是一个到处制造混乱的“实习生”？ 答案往往取决于你是否为 AI 提供了明确的上下文。这就是 AGENTS.md 规范诞生的原因。

与此同时，越来越多的开发者在参与开源项目贡献时使用自己的AI Coding Agent，这包括向Linux内核提交代码。所以开源项目及其维护者不得不积极面对这一现实变化。

1. 什么是 AGENTS.md？​

简单来说：README.md 是写给人类看的，而 AGENTS.md 是专门写给 AI 编程工具看的。

它是一个放置在项目根目录下的标准 Markdown 文件（遵循 https://agents.md 开放规范），用于为 AI Agent 定义在当前仓库中工作的操作规范、架构约束、技术栈细节以及常用的终端命令。

2. 为什么要使用 AGENTS.md？​

在项目中引入 AGENTS.md 能带来立竿见影的收益：

消除“幻觉”与过度重构：AI 经常会根据其训练数据推荐过时的库，或者在修复小 Bug 时擅自重构不相关的文件。在 AGENTS.md 中设定严格的边界，可以大幅降低这类风险。

统一跨工具的行为：无论贡献者使用的是 Cursor、Copilot 还是独立的 CLI ，AGENTS.md 都能作为唯一的事实来源（Single Source of Truth），确保 AI 生成的代码符合你项目的风格指南。

大幅降低新贡献者的上手门槛：当开发者启动 AI 助手时，AI 会自动读取该文件，了解如何构建项目、运行测试和格式化代码，无需开发者反复手动向 AI 投喂冗长的上下文。

提升测试与交付的成功率：通过提供精确的测试和校验命令，你可以要求 AI 在修改代码后自行验证结果。

3. 如何编写高质量的 AGENTS.md？​

编写给 AI 看的文档，与写给人类看的文档有本质区别。AI 不需要客套话，需要的是可执行的命令和明确的规则。

第一步：在根目录创建文件 直接在仓库根目录新建 AGENTS.md ，并在头部明确其用途和角色设定。如果是一个大型单仓项目，那么你也可以在不同模块下创建专属于该模块的 AGENTS.md ，这完全没有问题，符合最佳实践。

第二步：指令命令化 (Command-First) 不要使用模糊的散文。例如，不要写“请确保代码通过测试”，而是直接提供命令，让 AI 可以通过退出码 (Exit Code) 来验证结果：

“在完成任何修改后，必须运行 npm run test 和 npm run lint。”

第三步：明确技术栈与代码规范 指出项目使用的具体库版本和约定俗成的写法，明确禁止 AI 引入你不想要的技术栈。

第四步：划定红线（边界） 明确告诉 AI 哪些目录是只读的，哪些文件是自动生成的、绝对不能手动修改的。

真实案例模板 以下是一个适用于前端项目的 AGENTS.md 示例，展示了如何清晰地向 AI 下达指令：

## AI 编程操作指南
你是一个资深的前端工程师。在修改本仓库的代码前，请严格遵循以下规则：

### 1. 技术栈与架构
-  这是一个使用 React 18 + TypeScript + Vite 的项目。
-  状态管理使用 Zustand，**请勿引入 Redux** 。
-  样式使用 Tailwind CSS。**禁止编写内联样式**  (`style={{...}}`)。

### 2. 编码规范
- 优先使用 `const`  而不是 `let` 。
- 在定义类型时，优先使用 `interface`  而不是  `type` 。
- 组件必须放置在 `src/components/`  目录下，并使用命名导出（Named Exports）。

### 3. 测试与验证
在完成任何代码修改后，你必须在终端执行以下命令验证更改：
- 运行测试： `npm run test`
- 类型检查： `npm run typecheck`
- 代码格式化： `npm run lint:fix`

### 4. 边界与限制
- **绝对不要**  修改 `src/legacy/` 目录下的任何文件，该目录已被标记为废弃。
-  不要尝试手动修改 `package-lock.json`。

当然，对于相对比较简单的项目，你完全可以尝试让Coding Agent在阅读了 AGENTS.md 官网的信息后自动帮你快速创建一个 AGENTS.md 文档，在经过你的评审后即可使用。

4. 结语​

在 AI 原生开发的浪潮中，让 AI 更好地理解你的项目，是维护代码质量和提升社区协作效率的关键。在你的开源项目中花几分钟添加一个 AGENTS.md，你将收获更高质量的 Pull Request 和更少的人工评审负担。

立刻行动起来，为你的代码库雇佣一个合格的“AI 守门人”吧！

相关链接​

· 7 min read
Chris (Gentle) Yang

近日OSI发布博文：以《开源人工智能定义》初稿为 2023 年深入探讨人工智能画上句号，回顾了本年对在开源AI定义上的努力并介绍了当前的最新成果。

OSI Open Source AI draft talking

深度探讨开源人工智能一事自2022年就在进行，由GitHub牵头，DataStax,Google参与，并在当年底发布了报告，主要内容如下：

概述​

  • 人工智能和机器学习简介
  • 人工智能的威力：有什么可怕的？
  • 数据集的重要性难以置信
  • AI/ML模型的神秘“黑匣子”
  • 我们该如何管理人工智能的风险？
  • 开源的作用和人工智能民主化的价值
  • 下一步是什么？解决我们最紧迫的问题
  • 致谢：深入探讨：人工智能 贡献者和赞助商

来到2023年，OSI继续在推进这项工作，其在官网通过时间线记录了整个过程，并表示：是时候有一个明确的定义了，我们正在推动一个多方利益相关者流程来定义“开源人工智能” 。今年的参与者包括了Amazon、GitHub、Google Open Source以及OSSC、GitLab、Sourcegraph和Weaviate。

开放的流程​

此次深度探讨是一系列现场和在线活动，收集开发和使用人工智能系统的个人开发者、律师、研究人员、非营利组织、公司和政府官员的意见和评论。

宏伟的目标​

OSI 正在召集全球专家，制定一套共同的原则，为人工智能从业人员重新创建无许可、务实和简化的合作，这与开源定义所做的工作类似。

你可以在 https://opensource.org/deepdive/#timeline 查看所有公开流程与记录。

OSI在其近日的博文中重点介绍了v0.0.3的主要内容及更新点，截止目前v0.0.4版本草稿已经出炉，以下是全文：

v0.0.4版本草稿 https://opensource.org/deepdive/drafts/the-open-source-ai-definition-draft-v-0-0-4/

v0.0.4草稿起始

注：本文件由三部分组成：序言，说明本文件的意图；开源人工智能本身的定义；以及评估许可证的清单。

本文件遵循经济与合作发展组织（OECD）对人工智能系统的定义： 人工智能系统是一种基于机器的系统，针对显式或隐式目标，从接收到的输入推断如何生成可以影响物理或虚拟环境的输出，例如预测、内容、建议或决策。不同的人工智能系统部署后的自主性和适应性水平各不相同。

有关 AI 系统定义的更多信息，请访问 OSI 博客。

前言​

为什么我们需要开源人工智能 (AI) 开源已经证明，当您消除学习、使用、共享和改进软件系统的障碍时，每个人都会受益匪浅。这些好处是使用遵守开源定义的许可证的结果。其好处可以归结为自主性、透明度和协作改进。 每个人都需要人工智能的这些好处。我们需要基本的自由，使用户能够构建和部署可靠且透明的人工智能系统。

超出范围的问题

开源人工智能定义没有说明如何开发和部署一个道德的、值得信赖的或负责任的人工智能系统，尽管它并没有阻止它。是什么让人工智能系统道德、负责任、值得信赖或有效，这是一个单独的讨论。我们支持解决这些问题的努力，包括通过适当的政府监管。

什么是开源人工智能​

要实现开源，人工智能系统需要根据法律条款提供，并授予以下自由：

将系统用于任何目的，无需征求许可。

研究系统如何工作并检查其组件。

出于任何目的修改系统，包括更改其输出

共享系统以供其他人出于任何目的进行修改或不修改使用。[提供一个基于机器学习的示例？]

评估许可证的清单​

待定

v0.0.4草稿结束

让我们共同关注和期待最终版本的发布，如果可能，也非常欢迎你的参与和评论。

相关链接​

PS: 本文所引用的OSI相关内容旨在传播开源及相关行业动态，其知识产权许可以OSI官网声明为准。