前言

这是我”AI Coding 经验总结”系列的第五篇文章。前几篇聊的是工具选型、工作流范式、Harness Engineering 这些偏宏观的话题，这篇回到一个更具体的问题：怎么写好一份 AGENTS.md？

「在代码仓库中放一份上下文文件，告诉 AI 工具这个项目是什么、怎么构建、有什么规矩」——这个做法现在已经有了一个统一的名字：AGENTS.md。在展开实践之前，先花一点篇幅介绍它的前世今生，已经了解的同学可以跳过。

AGENTS.md 是什么？

AGENTS.md 是一个简单的开放格式，用于指导 AI Coding Agent 在你的项目中工作。你可以把它理解为给 AI 看的 README——README.md 是给人类看的项目说明，AGENTS.md 则是给 AI Agent 看的项目指令，包含构建命令、编码规范、测试要求、安全注意事项等 AI 需要知道的上下文。

官方建议的使用方式很简单：

1. 在仓库根目录创建一个 AGENTS.md 文件
2. 写上对 Agent 有用的内容：项目概述、构建测试命令、代码风格、安全注意事项
3. 补充额外指引：commit 规范、部署步骤、安全陷阱——任何你会告诉项目新成员的东西
4. 大型 monorepo 可以在子目录放嵌套的 AGENTS.md，Agent 会读最近的那个（OpenAI 自己的仓库有 88 个 AGENTS.md）

格式上没有任何强制要求，就是标准的 Markdown，用什么标题、写什么内容完全自由。

前世今生

这个概念最早由 Anthropic 通过 Claude Code 的 CLAUDE.md 普及。Claude Code 运行时会自动加载当前目录下的 CLAUDE.md，把内容注入到发给模型的请求中。这个设计简单而有效——维护好一份上下文文件，Agent 的表现就会变好；表现变好了，你就更愿意用它，进而更愿意维护这份文件，形成正向循环。

随后各家 AI Coding 工具跟进了自己的版本，一度各自为政：

工具	上下文文件
Claude Code	CLAUDE.md
Cursor	.cursorrules / .cursor/rules
Copilot	.github/copilot-instructions.md
Gemini CLI	GEMINI.md
Cline	.clinerules
AMP (Sourcegraph)	AGENT.md（单数）
OpenAI Codex	AGENTS.md（复数）

这种碎片化意味着团队需要为不同工具维护多份内容相同的配置文件，改一次规则要同步好几个地方。

2025 年 5 月，Sourcegraph 旗下的 AMP 率先提议统一标准，建议用 AGENT.md（单数），并注册了 agent.md 域名。随后 OpenAI 宣布买下了 agents.md 域名，提议用 AGENTS.md（复数），理由是多个 Agent 会共用同一份配置。AMP 随即主动让步对齐，将 agent.md 重定向到 agents.md。

最终 AGENTS.md 成为事实标准，由 Linux Foundation 下属的 Agentic AI Foundation 托管。截至 2026 年初，GitHub 上已有超过 6 万个开源项目使用这个格式。Cursor、Kiro、灵码、Qoder、Copilot 等主流工具均已支持。Claude Code 虽然仍用 CLAUDE.md，但内容完全通用，一个软链接即可兼容：ln -s AGENTS.md CLAUDE.md。

过去半年里，我为手头的多个项目都维护了 AGENTS.md——有管控系统、有内核引擎代码、有产品基线、也有文档系统。不同项目的技术栈、仓库结构、团队规模各不相同，但在 AGENTS.md 的实践上逐渐收敛到了一套相似的方法论。这篇文章我挑了其中投入最多、也最通用的一个场景——管控系统（Spring Boot + React 的前后端分离项目）来展开介绍，希望对正在写或者想写 AGENTS.md 的同学有参考价值。

本文摘要：

• 从零配置一台博客服务器的完整实践：SSH 免密登录、Nginx 部署、Cloudflare DNS、GitHub Webhook 自动部署
• 全程没有离开 Qoder 终端，涉及 5 个外部系统的联动操作
• Qoder 的能力边界远不止写代码，它可以操作你能 SSH 到的任何机器、调用任何有 API 的服务
• AI First 思维：遇到任何事情，先想想能不能用 AI 解决

又要配服务器了

我的博客一直部署在自己的 ECS 上，最近旧的那台到期了，续费价格看了一眼就没有续费的欲望，索性买了一台新的。

熟悉我博客的读者可能知道，这已经不是我第一次折腾博客服务器了。上一次配这套环境的时候，我开了四五个终端窗口，一边翻 Nginx 文档一边调配置，中间还要切到浏览器登录 Cloudflare 控制台改 DNS、登录 GitHub Settings 配 Webhook，前前后后折腾了大半天。流程我都很熟，但就是琐碎，每次换服务器都得把这些步骤重新走一遍，属于那种”会做但不想做”的事情。

但这次情况不一样了——我手边有 Qoder。

既然日常写代码都在 Qoder 里，配服务器这种事情不妨也试试全程在 Qoder 里完成。不是让它帮我写一个部署脚本，而是让它直接操作——SSH 到服务器装软件、调用 Cloudflare API 改 DNS、通过 GitHub CLI 创建 Webhook。整个过程还挺顺畅的，这篇文章就是把这个过程完整记录下来。

如果你还把 AI Coding 工具仅仅当作”写代码的助手”，希望这篇文章能帮你打开一些思路。

使用 Qoder 开发真实项目

本文整理自《Qoder Together 上海站 | 2025/12/20》的直播分享。

我今天分享的主题是 Agentic Coding 认知升级与实践避坑指南。我相信大家都能感受到，AI 编程的浪潮已经拍在了我们的键盘上，问题不是”用不用”，而是”怎么用才能让它成为真正的生产力，而不是解决了代码的产出，又引入了新的麻烦”。

自我介绍

首先进行下自我介绍，我是徐靖峰，花名是岛风，来自阿里云专有云 PaaS 中间件团队，主要负责网关产品的研发工作。同时我也是一个开源贡献者，主要参与 Higress 和 Himarket 项目。

我并不是 Qoder 团队的同学，所以可以更加客观地去评价 Qoder。

大家好，我是岛风。订阅了两个月 Qoder 之后，我想通过这篇文章分享一些个人使用心得和感受，希望能和大家交流 AI 编码的经验。

Qoder 是什么

Qoder 是阿里在 Agentic Coding 赛道上交出的一份答卷，一个对标 Cursor、Claude Code 的智能编码平台。官网链接：https://qoder.com/referral?referral_code=giB4Qp8oAraMl3HnoBEqCoIavUwbZJPO

目前提供了几种不同的形态供用户选择

Qoder IDE：一个独立的、拥有图形化界面的 IDE，核心功能包括 Agent 模式、问答模式、Quest 模式。

Qoder CLI：命令行工具，为喜欢终端操作的开发者准备。

Qoder JetBrains 插件：对于离不开 JB 全家桶的开发者，Qoder 提供了无缝集成的插件。

我为什么用 Qoder

AI Coding 产品作为一个消费级的产品，除去公司采购报销场景，自行使用基本都是付费上班模式，所以还是会用脚投票的。

公司已经对部分部门开放了 Cursor 的申请入口，但很不巧我所在的部门还没有开放申请入口。

于是便采取了比价模式，以 Curosr 和 Qoder 对比为例，二者同样采取订阅制，同样的 Pro 订阅 Qoder 的价格是 Curosr 的一半，再叠加上新用户赠送 2000 credits 和首次订阅 2 刀的“真香”福利，不动心真的很难。

至于为什么没考虑其他工具：

• Claude Code。口碑虽好，但国内使用据说极易被封，加上公司强大的安全扫描，用“黑科技”强行上车，风险未知，得不偿失。
• 字节 Trae 和美团的 Catpaw。主要是产品成熟度和友商因素。在没有形成压倒性口碑之前，没必要投入太多精力去“陪跑”。