多-AI-Agent-上下文规范调研手册

核对日期：2026-05-11

1. 问题背景

1.1 为什么不同 AI Agent 需要不同规则文件

AI 编程工具读取项目规则的方式并没有统一到一个强制标准。不同工具的入口文件、加载层级、作用域、触发条件和上下文预算都不一样，所以同一组团队规范如果只写在一个工具专属文件里，其他 Agent 很可能完全读不到，或者只能读到一部分。

典型差异有 4 类：

差异点	影响	示例
文件名不同	工具只扫描自己的默认入口	Codex 读 `AGENTS.md`，Claude Code 读 `CLAUDE.md`，Gemini CLI 默认读 `GEMINI.md`
作用域不同	根目录、子目录、用户级规则的优先级不同	Claude Code 会向上查找 `CLAUDE.md`，Cursor 的 `.cursor/rules/*.mdc` 可以按 glob 触发
格式能力不同	有的只是 Markdown，有的支持 frontmatter、glob、手动触发	Cursor、Windsurf、Cline 支持更细粒度的规则文件
加载时机不同	有的启动时加载，有的在模型判断相关时再加载	Windsurf 的 `model_decision` 规则只先暴露描述，命中后再读全文

这意味着“规则文件”不是简单的 README 副本，而是 Agent 的输入契约。它决定 Agent 在修改代码前能否知道：

当前项目技术栈、目录边界和禁止修改区域。
TypeScript、React、Vue、小程序、uni-app 等代码规范。
构建、测试、提交、发布的实际命令。
安全底线，例如禁止硬编码密钥、禁止直接渲染未转义用户输入。
团队对输出语言、注释风格、PR 描述和 Conventional Commits 的约定。

1.2 目前有没有所有 Agent 都统一读取的事实标准

结论：还没有一个所有主流 Agent 都强制读取、语义完全一致的事实标准。

AGENTS.md 正在成为最接近“通用入口”的文件名。它的优势是简单、开放、Markdown 格式、适合放在仓库根目录，也被越来越多工具识别。但它仍然不是完整统一方案，原因是：

有些工具只把 AGENTS.md 当作简单全局规则，不支持 path scoped rules。
有些工具仍优先使用自己的原生规则系统，例如 Cursor 的 .cursor/rules/*.mdc、Claude Code 的 CLAUDE.md、Windsurf 的 .windsurf/rules/*.md。
不同工具对“根目录规则、子目录规则、用户级规则、组织级规则”的优先级解释不同。
AGENTS.md 本身没有 schema，也没有标准字段，适合人工编写，但不适合做机器级验证。

所以工程上更稳的做法不是押注单一文件，而是采用：

一份源规则目录
  -> 生成多个 Agent 入口文件
  -> 每个工具读取自己的最佳入口
  -> 通过脚本和 CI 防止规则漂移

1.3 这份手册的适用范围

这份手册面向个人和团队内部工程使用，重点覆盖前端工程项目、AI coding skills、hooks、项目规则同步和多 Agent 协作，不写成公开宣传文。

优先关注这些场景：

同一个项目里同时使用 Codex、Claude Code、Cursor、GitHub Copilot、Gemini CLI、Windsurf、Cline。
需要把全局前端规范同步到项目级规则。
希望团队只维护一份源规则，避免 AGENTS.md、CLAUDE.md、.cursor/rules/*.mdc 内容长期漂移。
希望规则足够具体，能约束 Agent 修改代码，而不是泛泛写“遵循最佳实践”。

2. 主流 Agent 规则文件对照

2.1 总览表

工具	推荐入口	支持范围	适合放什么	注意点
OpenAI Codex	`AGENTS.md`	仓库根目录和子目录规则，具体层级依赖 Codex 版本与配置	项目约定、构建测试命令、安全边界、提交规范	`AGENTS.md` 是主入口，但不是强 schema
Claude Code	`CLAUDE.md`、`.claude/CLAUDE.md`、用户级 `~/.claude/CLAUDE.md`	企业、项目、用户、局部记忆；支持 `@path` 导入	项目架构、工作流、常用命令、团队规则	团队共享规则放 `CLAUDE.md`，个人本地偏好可放已 gitignore 的 `CLAUDE.local.md`
GitHub Copilot	`.github/copilot-instructions.md`、`.github/instructions/*/.instructions.md`、`AGENTS.md`	仓库级、路径级、部分 agent 指令	Copilot Chat、CLI、cloud agent、code review 相关约定	不同 Copilot 环境支持的指令类型不同，需要按使用入口核对
Cursor	`.cursor/rules/*.mdc`、根目录 `AGENTS.md`	Project Rules、User Rules、AGENTS.md、legacy `.cursorrules`	细粒度编码规范、按 glob 触发的前端/后端/测试规则	`.cursorrules` 已是 legacy，复杂项目优先 `.cursor/rules/*.mdc`
Gemini CLI	`GEMINI.md`，可配置 `context.fileName` 读取 `AGENTS.md` 等	全局、项目、父目录、子目录；支持 `@file.md` 导入	Gemini CLI 专用上下文、可复用通用规则	默认文件名是 `GEMINI.md`，但可配置多个上下文文件名
Windsurf Cascade	`.windsurf/rules/*.md`、`AGENTS.md`、全局规则	global、workspace、system、AGENTS.md；支持 `always_on`、`glob`、`model_decision`、`manual`	IDE 内 Cascade 的编码标准、路径触发规则、企业规则	workspace 单规则有长度限制，适合拆分
Cline	`.clinerules/`、`AGENTS.md`、Cursor/Windsurf 兼容规则	workspace、global；可识别多种工具规则	VS Code / Cursor / JetBrains 中的 Cline 任务约束	支持规则开关；`.clinerules/` 下建议按主题拆分
llms.txt	`/llms.txt`	网站根路径	给 LLM 的站点级内容地图	不是代码 Agent 的项目规则文件，适合文档站和公开知识库

2.2 Codex 与 `AGENTS.md`

AGENTS.md 的定位是“给 coding agents 的 README”。它应该包含人类 README 不一定需要、但 Agent 执行任务前必须知道的信息：

安装依赖、启动服务、运行测试、构建和 lint 命令。
项目目录结构和模块边界。
代码风格、类型规范、测试规范。
安全要求和不应触碰的文件。
PR、commit、review、发布流程。

推荐把根目录 AGENTS.md 作为跨 Agent 的公共入口，再按需要在子目录放局部 AGENTS.md。对前端 monorepo，可用如下结构：

AGENTS.md
packages/admin/AGENTS.md
packages/miniprogram/AGENTS.md
packages/shared/AGENTS.md

根目录写全局规则，子目录只写差异，不重复大段公共规范。

2.3 Claude Code 与 `CLAUDE.md`

Claude Code 的记忆系统比单文件规则更丰富。常见层级包括：

企业级：macOS 可放在 /Library/Application Support/ClaudeCode/CLAUDE.md。
项目级：./CLAUDE.md 或 ./.claude/CLAUDE.md。
用户级：~/.claude/CLAUDE.md。
自动记忆：Claude Code 可把会话中学到的项目事实写入本地 memory。

CLAUDE.md 支持 @path/to/file 导入，这是做“源规则拆分”的关键能力。例如：

# Project Instructions

@.agent-context/core.md
@.agent-context/frontend.md
@.agent-context/security.md
@.agent-context/project.md

建议把 CLAUDE.md 作为 Claude Code 的适配入口，不把所有内容直接堆进去。这样后续更新 .agent-context/ 后可以自动生成或直接 import。

2.4 GitHub Copilot instructions

GitHub Copilot 的规则入口至少要区分 3 类：

类型	路径	用途
仓库级 instructions	`.github/copilot-instructions.md`	给整个仓库的 Copilot 上下文
路径级 instructions	`.github/instructions/*/.instructions.md`	对特定目录或文件类型生效
Agent instructions	`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`	部分 Copilot agent / CLI / cloud agent 场景使用

实际落地时建议保留 .github/copilot-instructions.md，因为它是 Copilot 体系里最明确的仓库级入口。同时可以生成 AGENTS.md，服务 Codex 和其他支持 AGENTS.md 的工具。

2.5 Cursor rules

Cursor 当前推荐 Project Rules：

.cursor/
  rules/
    core.mdc
    frontend.mdc
    security.mdc
    testing.mdc

.mdc 文件可以包含元数据和内容，适合做“按场景加载”。常见类型包括：

Always：每次都进入上下文。
Auto Attached：命中文件 glob 时进入上下文。
Agent Requested：模型根据 description 判断是否需要。
Manual：用户手动 @ 提及。

示例：

---
description: React 和 TypeScript 前端组件开发规则
globs:
  - "src/**/*.tsx"
alwaysApply: false
---

# Frontend Rules

- 新增 React 组件必须使用 TypeScript 类型标注 props。
- 不允许使用裸 `any`，无法确定类型时先用 `unknown` 再收窄。
- 用户输入进入 DOM 前必须转义，不使用 `dangerouslySetInnerHTML` 处理用户输入。

根目录 AGENTS.md 可以作为 Cursor 的简单入口，但复杂前端项目仍建议生成 .cursor/rules/*.mdc，因为它的 path scope 更清晰。

2.6 Gemini CLI 与 `GEMINI.md`

Gemini CLI 默认读取 GEMINI.md，并支持层级上下文：

~/.gemini/GEMINI.md 作为用户级默认规则。
当前工作区、父目录或受信任根目录中的 GEMINI.md。
子目录中的 GEMINI.md。

它也支持用配置把上下文文件名改成或扩展为 AGENTS.md：

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

如果团队已经采用 AGENTS.md，Gemini CLI 可以通过配置复用它；如果希望保留 Gemini 专属说明，则生成 GEMINI.md。

2.7 Windsurf Cascade rules

Windsurf 把 Rules、AGENTS.md、Workflows、Skills 和 Memories 区分得比较清楚：

能力	适合内容
Rules	行为约束、编码规范、项目限制
AGENTS.md	零配置、目录级规则
Workflows	部署、评审、发布等可重复流程
Skills	需要脚本、模板、参考文件支持的复杂任务
Memories	会话中自动生成的临时或经验性上下文

Windsurf workspace 规则建议放在：

.windsurf/
  rules/
    frontend.md
    testing.md
    security.md

示例：

---
trigger: glob
globs: src/**/*.{ts,tsx,vue}
---

# Frontend Rules

- TypeScript 默认严格模式，不允许裸 `any`。
- React / Vue 组件必须遵循项目现有目录和状态管理约定。
- 修改交互逻辑后必须说明影响的平台范围。

2.8 Cline rules

Cline 的主规则目录是 .clinerules/：

.clinerules/
  01-core.md
  02-frontend.md
  03-security.md
  04-testing.md

Cline 也会识别部分其他工具的规则文件，例如 .cursorrules、.windsurfrules、AGENTS.md。但如果团队主要使用 Cline，仍建议生成 .clinerules/，因为它能被 Cline UI 管理和开关控制。

2.9 `llms.txt` 的定位

llms.txt 是网站层面的 AI 可读索引，通常放在网站根路径 /llms.txt，用于告诉 LLM 哪些页面最重要、每个页面的用途是什么。它适合：

文档站。
API 文档。
公开知识库。
产品官网的 AI 可读导航。

它不适合替代 AGENTS.md 或 CLAUDE.md。原因是：

llms.txt 面向网站理解和引用，不面向本地代码修改。
它通常暴露在公网，不应包含内部命令、私有目录、密钥策略细节或仓库结构敏感信息。
它不会天然被 Codex、Claude Code、Cursor 等本地 Agent 当作项目规则入口。

对当前 AI 知识库项目，llms.txt 可以作为 Docusaurus 文档站的后续增强项，但不是本次多 Agent 规则治理的核心入口。

3. 现有标准与工具调研

3.1 `AGENTS.md`：最接近通用入口，但不是完整治理层

AGENTS.md 的最大价值是低成本：

普通 Markdown。
文件名固定。
对人类和 Agent 都可读。
可放根目录，也可放子目录。
适合直接提交到 Git。

它的不足也很明确：

没有强 schema，无法直接验证“必须包含安全规范、测试命令、提交规范”。
没有统一的 frontmatter 或 glob 规则。
不同工具对嵌套 AGENTS.md 的加载行为不完全一致。
对复杂项目，单文件会变长，导致上下文浪费。

所以推荐把 AGENTS.md 视为“通用输出物”，而不是“唯一源文件”。

3.2 `CLAUDE.md`、`.cursor/rules`、`.windsurf/rules`：工具原生能力仍有价值

很多团队会问：既然 AGENTS.md 越来越通用，是否可以删掉工具专属文件？

答案：不建议一刀切删除。原因是工具原生规则通常提供额外能力：

Claude Code 的 @path imports 和多层 memory 更适合长规则拆分。
Claude Code 的 .claude/rules/*.md 可做路径级规则，适合大型项目减少无关上下文。
Cursor .mdc 支持 glob、manual、agent requested 等触发方式。
Windsurf 规则有 trigger、globs、model_decision 等模式。
Cline .clinerules/ 支持规则开关和条件规则。
Copilot 的 .github/instructions/**/*.instructions.md 更贴近 GitHub 平台上的路径级约束。

工程策略应该是：

源规则保持工具无关
适配入口保留工具能力
生成器负责把公共规则转换成各工具格式

3.3 Agent Rules Builder 等现成工具

现有工具可以作为参考或临时生成器，但不建议直接替代项目内治理：

工具	能力	适合场景	风险
Agent Rules Builder	从语言、框架、类别选择规则，导出 Cursor、Claude、Copilot、Windsurf、Cline、Codex、Gemini 等格式	快速生成 baseline	规则来自社区模板，需要人工贴合本项目
ClaudeMDEditor	可视化管理 Claude、Cursor、Copilot、Windsurf、Gemini、Codex 等配置	个人多项目管理	外部工具，不应成为团队 CI 的唯一依赖
dot-agents	试图把多 Agent 配置集中到 `~/.agents/`	个人本机统一配置	团队仓库仍需要可审计、可版本化的规则
agentmd	schema 化 `AGENT.md` 并生成多工具输出	想要强验证和 adapter 的团队	生态成熟度和团队接受度需要评估

推荐做法：

可以借鉴这些工具的文件映射和模板分类。
团队内部的源规则仍放在仓库中，走 code review。
生成器逻辑也放在仓库中，不依赖网页手工导出。

4. 推荐架构

4.1 总体结论

推荐架构：单一源规则目录 + 多 Agent 入口文件生成。

设计原则：

.agent-context/ 是唯一人工维护源。
Agent 入口文件是生成物，但可以提交到 Git，方便工具直接读取。
生成文件头部标明“由脚本生成，不要手改”。
如需工具专属差异，放在 .agent-context/adapters/<tool>.md 或生成器模板中。
CI 检查生成物是否和源规则一致，防止手改漂移。

4.2 推荐目录结构

.
├── .agent-context/
│   ├── core.md
│   ├── frontend.md
│   ├── security.md
│   ├── testing.md
│   ├── git.md
│   ├── project.md
│   ├── adapters/
│   │   ├── claude.md
│   │   ├── cursor.md
│   │   ├── copilot.md
│   │   ├── gemini.md
│   │   ├── windsurf.md
│   │   └── cline.md
│   └── manifest.json
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
├── .github/
│   ├── copilot-instructions.md
│   └── instructions/
│       ├── frontend.instructions.md
│       └── testing.instructions.md
├── .cursor/
│   └── rules/
│       ├── core.mdc
│       ├── frontend.mdc
│       └── security.mdc
├── .windsurf/
│   └── rules/
│       ├── frontend.md
│       └── security.md
├── .clinerules/
│   ├── 01-core.md
│   ├── 02-frontend.md
│   └── 03-security.md
└── scripts/
    └── generate-agent-context.mjs

4.3 源规则文件职责

文件	内容边界	示例
`.agent-context/core.md`	交流方式、工作流程、影响范围说明、复杂任务先给方案	默认中文交流；复杂任务先给方案再动手
`.agent-context/frontend.md`	前端工程规范	TypeScript strict、React / Vue、小程序、uni-app 规范
`.agent-context/security.md`	安全底线	禁止硬编码密钥；用户输入校验；禁止未转义 HTML
`.agent-context/testing.md`	质量验证	修改后运行 lint、typecheck、单测；说明无法运行的原因
`.agent-context/git.md`	提交和 PR	Conventional Commits；scope 必填；不使用 `update`
`.agent-context/project.md`	当前项目事实	本项目目录、构建命令、发布方式、不可公开目录

project.md 应该是最容易变的文件，其他文件尽量稳定。

4.4 规则内容的颗粒度

规则要可执行，不要写空话。

不推荐：

- 写高质量代码。
- 注意安全。
- 遵循最佳实践。

4.5 哪些内容不应该写进规则

不要把规则文件变成泄密入口或上下文垃圾桶：

不写 AppID、AppSecret、Token、密码、内网地址。
不写一次性任务细节，例如“今天修某个按钮”。
不写大段业务数据或日志。
不写可以从代码直接看出的低价值信息。
不把长文档全文复制进规则，改用路径引用或摘要。
不写互相冲突的要求，例如“一律不改测试”和“修改逻辑必须补测试”同时存在。

5. 落地步骤

5.1 第 1 步：建立源规则目录

先创建 .agent-context/，把全局前端工程师配置拆成稳定模块。

.agent-context/
  core.md
  frontend.md
  security.md
  testing.md
  git.md
  project.md

建议从现有规则中拆出这些段落：

身份定位和协作偏好 -> core.md
TypeScript、命名、注释、前端框架规范 -> frontend.md
密钥、输入校验、网络请求、XSS 防护 -> security.md
lint、typecheck、单测、可视化验证 -> testing.md
commit message、scope、PR 说明 -> git.md
当前仓库事实 -> project.md

5.2 第 2 步：定义 manifest

manifest.json 描述哪些源文件生成哪些目标文件。

{
  "version": 1,
  "sources": [
    "core.md",
    "frontend.md",
    "security.md",
    "testing.md",
    "git.md",
    "project.md"
  ],
  "targets": {
    "agents": "AGENTS.md",
    "claude": "CLAUDE.md",
    "gemini": "GEMINI.md",
    "copilot": ".github/copilot-instructions.md",
    "cursor": ".cursor/rules",
    "windsurf": ".windsurf/rules",
    "cline": ".clinerules"
  }
}

5.3 第 3 步：生成通用 `AGENTS.md`

AGENTS.md 应该包含所有工具都能理解的高信号规则：

# AGENTS.md

> Generated from `.agent-context/`. Do not edit directly.

## 工作方式

@generated from core.md

## 前端工程规范

@generated from frontend.md

## 安全规范

@generated from security.md

## 验证规范

@generated from testing.md

## Git 规范

@generated from git.md

## 项目上下文

@generated from project.md

如果目标工具不支持 @generated 这种标记，它也只是普通文本，不影响读取。真正生成时建议直接展开内容，而不是依赖所有工具支持 import。

5.4 第 4 步：生成 Claude / Gemini 入口

Claude Code 和 Gemini CLI 都支持 import 机制，但为了减少工具差异，建议默认生成“展开后的完整文件”。如果文件太长，再改成 import 版。

CLAUDE.md 示例：

# CLAUDE.md

> Generated from `.agent-context/`. Do not edit directly.

## 工作方式

...

## Claude Code 适配说明

- 优先遵循本文件中的项目级规则。
- 如规则冲突，以当前用户明确输入为准。
- 复杂任务先说明影响范围和执行方案，再改代码。

GEMINI.md 示例：

# GEMINI.md

> Generated from `.agent-context/`. Do not edit directly.

## 工作方式

...

## Gemini CLI 适配说明

- 本文件用于 Gemini CLI 的项目级上下文。
- 如果同时配置读取 `AGENTS.md`，避免重复注入相同规则。

5.5 第 5 步：生成 Copilot instructions

.github/copilot-instructions.md 建议聚焦仓库级规则，避免过长。

# GitHub Copilot Instructions

> Generated from `.agent-context/`. Do not edit directly.

## Repository Rules

- 默认使用中文解释工程判断。
- TypeScript 严格模式，不允许裸 `any`。
- 任何用户输入都必须经过合法性校验。
- 修改代码后优先运行项目约定的 lint、typecheck、test。

路径级 instructions 可按文件类型生成：

.github/instructions/frontend.instructions.md
.github/instructions/testing.instructions.md

5.6 第 6 步：生成 Cursor / Windsurf / Cline 细粒度规则

Cursor：

.cursor/rules/core.mdc
.cursor/rules/frontend.mdc
.cursor/rules/security.mdc
.cursor/rules/testing.mdc

Windsurf：

.windsurf/rules/core.md
.windsurf/rules/frontend.md
.windsurf/rules/security.md

Cline：

.clinerules/01-core.md
.clinerules/02-frontend.md
.clinerules/03-security.md

建议映射：

源规则	Cursor	Windsurf	Cline
core	Always	`always_on`	always on
frontend	glob `src/*/.{ts,tsx,vue,js,jsx,wxml,wxss,axml,acss}`	`trigger: glob`	`paths` frontmatter
security	Always	`always_on`	always on
testing	glob `*/.{test,spec}.{ts,tsx,js}`	`trigger: glob`	`paths` frontmatter

5.7 第 7 步：生成器方案

当前不需要马上生成脚本，但后续可以用 Node.js / TypeScript 写一个无依赖或低依赖生成器。

核心逻辑：

type SourceName =
  | "core"
  | "frontend"
  | "security"
  | "testing"
  | "git"
  | "project";

interface Manifest {
  version: number;
  sources: `${SourceName}.md`[];
  targets: {
    agents: string;
    claude: string;
    gemini: string;
    copilot: string;
    cursor: string;
    windsurf: string;
    cline: string;
  };
}

interface GeneratedFile {
  path: string;
  content: string;
}

生成流程：

read manifest
read .agent-context/*.md
validate required sections
render AGENTS.md
render CLAUDE.md
render GEMINI.md
render .github/copilot-instructions.md
render .cursor/rules/*.mdc
render .windsurf/rules/*.md
render .clinerules/*.md
format markdown
write files

建议命令：

{
  "scripts": {
    "agent-context:generate": "node scripts/generate-agent-context.mjs",
    "agent-context:check": "node scripts/generate-agent-context.mjs --check"
  }
}

CI 检查：

npm run agent-context:generate
git diff --exit-code AGENTS.md CLAUDE.md GEMINI.md .github .cursor .windsurf .clinerules

5.8 第 8 步：在项目中逐步启用

建议分 3 个阶段：

阶段	动作	验收标准
Phase 1	手动创建 `.agent-context/` 和 `AGENTS.md`	Codex 能读取项目规则；规则覆盖工作方式、前端、安全、Git
Phase 2	增加 `CLAUDE.md`、Copilot、Cursor 规则	多工具入口存在，内容不冲突
Phase 3	增加生成器和 CI check	只改源规则即可生成所有入口，手改生成物会被 CI 拦截

6. 维护规范

6.1 规则变更流程

规则文件会直接影响 Agent 改代码的方式，应该像代码一样 review。

推荐流程：

提出规则变更
  -> 修改 .agent-context/*
  -> 运行生成器
  -> 检查生成文件 diff
  -> 由至少 1 位熟悉项目的人 review
  -> 合并

变更时必须回答：

这条规则解决了什么反复出现的问题？
它会不会和已有规则冲突？
它是否足够具体，Agent 能否执行？
是否应该是全局规则，还是只对某类文件生效？
是否包含敏感信息？

6.2 规则更新触发条件

出现以下情况应更新规则：

Agent 第 2 次犯同一类错误。
code review 发现 Agent 本应知道的项目约定。
项目新增构建、测试、发布命令。
技术栈发生变化，例如 React 版本、Vue 版本、小程序框架、状态管理方案调整。
安全策略变化，例如新增富文本白名单、登录态处理、接口签名方式。
团队提交规范或 PR 模板调整。

6.3 冲突处理规则

建议明确优先级：

用户当前明确指令
  > 项目级规则
  > 子目录 / 文件类型规则
  > 用户全局偏好
  > 工具自动记忆

但不同工具真实加载顺序可能不同，所以规则文本要减少冲突。不要在 core.md 写“所有任务直接动手”，又在 project.md 写“复杂任务必须先给方案”。应该统一成：

- 简单任务直接处理。
- 复杂任务先说明方案、影响范围和验证方式，再改代码。

6.4 周期性检查清单

每月或每个大版本做一次规则体检：

AGENTS.md、CLAUDE.md、GEMINI.md 是否由同一源生成。
.cursor/rules、.windsurf/rules、.clinerules 是否和源规则一致。
是否存在废弃命令，例如旧 package manager、旧测试命令。
是否包含敏感信息或内部 URL。
是否有重复、冲突、过时的规则。
是否有规则太长，导致上下文浪费。
是否需要把单个大规则拆成路径级规则。

6.5 当前项目的建议落地方案

结合当前 /Users/luhanguo/Desktop/AI 的 AI Agent 知识库工作流，建议先不一次性引入所有工具入口，而是按优先级落地：

根目录建立 AGENTS.md：作为 Codex 和通用 Agent 入口。
建立 .agent-context/：把当前全局前端规则和 AI 知识库项目约定拆开。
补 CLAUDE.md：如果继续在本机使用 Claude Code，可直接复用 .agent-context/。
如果后续用 Cursor / Windsurf / Cline 修改文档站或前端工程，再生成对应 rules 目录。
对 agent-docs-site/ 可单独放子目录规则，说明 Docusaurus 同步边界：AI Agent知识体系大全/ 是源，00-项目控制台/ 不进入公开站点。

建议首版源规则：

.agent-context/
  core.md          # 中文交流、复杂任务先方案、修改前说明影响范围
  frontend.md      # TypeScript / React / Vue / 小程序 / uni-app
  security.md      # 密钥、输入校验、XSS、网络请求封装
  docs.md          # AI 知识库写作深度、资料来源、断链检查
  git.md           # Conventional Commits
  project.md       # /Users/luhanguo/Desktop/AI 项目事实

7. 建议模板

7.1 `.agent-context/core.md`

# Core Collaboration Rules

- 默认使用中文交流。
- 默认用户是高级前端工程师，不解释基础概念，直接给专业方案和关键判断理由。
- 简单任务直接处理；复杂任务先说明方案、影响范围和验证方式。
- 修改代码前说明影响范围。
- 涉及兼容性问题时，主动标明微信小程序、支付宝小程序、H5、App、React、Vue 等平台差异。
- 不输出空泛建议，必须结合当前项目文件、命令和真实约束。

7.2 `.agent-context/frontend.md`

# Frontend Engineering Rules

## TypeScript

- 默认严格模式，不允许裸 `any`。
- 用 `unknown` 替代 `any`，必要时用类型守卫收窄。
- 接口和类型使用语义化命名，不加 `I` 前缀。
- 枚举优先用 `as const` 对象，避免 `const enum` 在 `isolatedModules` 下的兼容问题。

## Naming

- 变量和函数使用 camelCase。
- 组件和类使用 PascalCase。
- 常量使用 SCREAMING_SNAKE_CASE。
- 文件使用 kebab-case；组件文件遵循项目现有约定。

## Comments

- 公共函数必须写 JSDoc。
- 复杂逻辑写“为什么”，不写“做什么”。
- TODO 必须包含日期和 issue 编号，例如 `// TODO(2026-03): #142 待优化`。

7.3 `.agent-context/security.md`

# Security Rules

- 禁止硬编码 AppID、AppSecret、Token、密码等敏感信息。
- 敏感配置通过环境变量注入，不提交 `.env` 文件。
- 用户输入必须做合法性校验，小程序端输入同样不可信。
- 网络请求必须走项目统一封装，不散落调用 `fetch`、`wx.request`、`my.request` 等原生 API。
- H5 / Web 禁止使用 `v-html` 或 `dangerouslySetInnerHTML` 处理用户输入；确需使用时必须说明净化方案。

7.4 `.agent-context/docs.md`

# Documentation Rules

- 面向工程落地，不写营销口吻。
- 每个结论尽量回答：为什么、什么时候适用、什么时候不适用。
- 核心文档必须包含机制、工程实现、生产实践、常见反模式和权威资料。
- 快速变化的信息必须联网核对，并在文末标注核对日期。
- 写 AI Agent 知识库时，不把“Agent 很智能”当结论，要解释机制、边界和失败条件。

8. 权威资料与延伸阅读

AGENTS.md official site: https://agents.md/
OpenAI Codex AGENTS.md guide: https://developers.openai.com/codex/guides/agents-md
OpenAI Codex CLI repository: https://github.com/openai/codex
OpenAI Codex AGENTS.md docs file: https://github.com/openai/codex/blob/main/docs/agents_md.md
Claude Code memory docs: https://docs.claude.com/en/docs/claude-code/memory
Claude Code project memory docs: https://code.claude.com/docs/en/memory
GitHub Copilot custom instructions: https://docs.github.com/en/copilot/how-tos/copilot-cli/add-custom-instructions
GitHub Copilot custom instructions support matrix: https://docs.github.com/en/copilot/reference/custom-instructions-support
Cursor rules docs: https://docs.cursor.com/context/rules
Cursor CLI rules note: https://docs.cursor.com/en/cli/using
Gemini CLI GEMINI.md context docs: https://google-gemini.github.io/gemini-cli/docs/cli/gemini-md.html
Windsurf Cascade memories and rules: https://docs.windsurf.com/windsurf/cascade/memories
Cline rules docs: https://docs.cline.bot/customization/cline-rules
Cline conditional rules docs: https://docs.cline.bot/features/conditional-rules
llms.txt proposal: https://llmstxt.org/
Agent Rules Builder: https://www.agentrulegen.com/about
Agent Rules Builder comparison guide: https://www.agentrulegen.com/compare

1. 问题背景​

1.1 为什么不同 AI Agent 需要不同规则文件​

1.2 目前有没有所有 Agent 都统一读取的事实标准​

1.3 这份手册的适用范围​

2. 主流 Agent 规则文件对照​

2.1 总览表​

2.2 Codex 与 AGENTS.md​

2.3 Claude Code 与 CLAUDE.md​

2.4 GitHub Copilot instructions​

2.5 Cursor rules​

2.6 Gemini CLI 与 GEMINI.md​

2.7 Windsurf Cascade rules​

2.8 Cline rules​

2.9 llms.txt 的定位​

3. 现有标准与工具调研​

3.1 AGENTS.md：最接近通用入口，但不是完整治理层​

3.2 CLAUDE.md、.cursor/rules、.windsurf/rules：工具原生能力仍有价值​

3.3 Agent Rules Builder 等现成工具​

4. 推荐架构​

4.1 总体结论​

4.2 推荐目录结构​

4.3 源规则文件职责​

4.4 规则内容的颗粒度​

4.5 哪些内容不应该写进规则​

5. 落地步骤​

5.1 第 1 步：建立源规则目录​

5.2 第 2 步：定义 manifest​

5.3 第 3 步：生成通用 AGENTS.md​

5.4 第 4 步：生成 Claude / Gemini 入口​

5.5 第 5 步：生成 Copilot instructions​

5.6 第 6 步：生成 Cursor / Windsurf / Cline 细粒度规则​

5.7 第 7 步：生成器方案​

5.8 第 8 步：在项目中逐步启用​

6. 维护规范​

6.1 规则变更流程​

6.2 规则更新触发条件​

6.3 冲突处理规则​

6.4 周期性检查清单​

6.5 当前项目的建议落地方案​

7. 建议模板​

7.1 .agent-context/core.md​

7.2 .agent-context/frontend.md​

7.3 .agent-context/security.md​

7.4 .agent-context/docs.md​

8. 权威资料与延伸阅读​