▲ AI 开发规则与安全协议模板

一套通用、可审计、跨工具的 AI 编程助手规则集。以 AGENTS.md 为唯一源头，自动同步到 Claude Code、Cursor、GitHub Copilot、Trae、OpenCode、Qoder 等主流工具的专属配置文件。

这个仓库是什么

本仓库解决一个具体问题：同一个项目往往会被多个 AI 编程工具交替使用——你在桌面用 Trae、在 IDE 里用 Cursor、在 GitHub 上用 Copilot、在终端用 Claude Code。如果每个工具各读各的规则，就会出现「Copilot 知道的约束 Claude 不知道」的割裂，AI 的行为在不同工具间不一致。

它把全部开发铁律、提示词、子角色定义、技能清单集中维护在一份 AGENTS.md 里，再用一个同步脚本生成各工具能直接读取的配置文件。改一处，全工具生效。

核心特征：

• 唯一源头：只维护 AGENTS.md，其余文件由 scripts/sync_rules.py 生成，不手工改。
• 跨工具保真：GitHub Copilot 不支持 @ 导入，脚本会把引用文件内联展开，保证每个工具拿到完整规则，而不是悬空的引用。
• 受限技能获取：内置 5 层递进的技能获取协议（标准库 → 包管理器 → 本地注册表 → 优先厂商官方仓库 → 受限自主搜索），避免 AI 随意从网上拉未知脚本。
• MCP 红线：MCP 涉及常驻进程与权限，绝对禁止 AI 自下载、自安装、自启动、自配置，只能由你手动在各工具里配。

兼容矩阵

文件结构

AI/
├─ AGENTS.md                      # 规则唯一源头（8 节 Project Rules & Safety Protocol）
├─ CLAUDE.md                      # 从 AGENTS.md 同步，供 Claude Code 读取
├─ GEMINI.md                      # 从 AGENTS.md 同步，供 Gemini CLI 读取
├─ .github/
│  └─ copilot-instructions.md    # 从 AGENTS.md 同步，供 GitHub Copilot 读取（@ 引用已内联）
├─ README.md                      # 本文件
├─ mcp.example.json              # MCP 配置示例模板（占位 token，各工具通用）
├─ scripts/
│  └─ sync_rules.py              # 同步脚本（仅用标准库）
└─ docs/
   ├─ INIT-PROMPT.md             # 新项目初始化配置指令（复制发给任意 AI 工具）
   ├─ prompts/
   │  ├─ system-prompt.md        # 英文 XML 系统提示词（含 <mcp_policy> 等）
   │  ├─ architect-subagent.md   # 架构师子角色
   │  └─ critic-subagent.md      # 审查官子角色
   └─ skills/
      ├─ registry.md             # 工具白名单 + 受限搜索协议（11 分类 + 优先厂商仓库 + 灵感仓库）
      ├─ git-sop.md              # Git 提交规范
      ├─ powershell-tips.md      # Windows 下 PowerShell 语法要点
      ├─ mcp-registry.md         # 可手动接入的 MCP 清单（仅参考）
      └─ tool-skill-mcp.md       # Tool / Skill / MCP 三者关系与落地结构

历史遗留的 .trae/ 目录已弃用；MCP 示例配置统一放在仓库根的 mcp.example.json，适配所有支持 MCP 的工具，不再绑定 Trae。

AI 该如何阅读本仓库

如果你是一个被接入本仓库（或被注入本仓库规则）的 AI 工具，按以下顺序读取即可完整理解规则与约束：

1. 先读 AGENTS.md —— 全部开发铁律的权威来源。8 节涵盖：工作流沟通、去 AI 味、变更范围、防死循环、安全保密、工程卫生、Shell 与 Git、技能获取，以及 Tool / Skill / MCP 管理策略。
2. 再读 docs/prompts/ —— 系统提示词与子角色定义（架构师 / 审查官），理解「先规划、后实现、再审查验证」的分工。
3. 按需读 docs/skills/：
   • 选工具前查 registry.md（白名单 + 受限搜索协议）；
   • 提交前查 git-sop.md；
   • Windows 环境查 powershell-tips.md；
   • 接入外部系统前查 mcp-registry.md（只读，不自动配置）。
4. 永远不要脱离上述文件自行发明规则，或从网上下载未知脚本直接执行。

阅读顺序本身就是一条「引导链」：README → AGENTS.md → prompts → skills。任何具体任务都从这套链里取对应约束，不另起炉灶。

怎么用（把规则引入你的项目）

方式一：直接拷贝（推荐，零依赖）

把下列文件复制到新项目根目录：

cp /path/to/AI/AGENTS.md ./AGENTS.md
cp /path/to/AI/CLAUDE.md ./CLAUDE.md
cp /path/to/AI/GEMINI.md ./GEMINI.md
cp -r /path/to/AI/.github ./.github
cp -r /path/to/AI/docs ./docs

方式二：git submodule（多项目统一更新）

cd your-new-project
git submodule add https://github.com/MS33834/AI.git .ai-rules
echo '@.ai-rules/AGENTS.md' > AGENTS.md

远程地址 https://github.com/MS33834/AI.git 是本规则模板仓库。若你 Fork 到自己的 GitHub 账号，请改成你的仓库地址。

验证是否生效

初始化后问智能体：「当前项目的编码规范和我定的开发铁律是什么？」
若它能准确答出「先规划后代码 / 歧义即停 / 禁 AI 味 / 用成熟库禁止手写底层 / 改动后必须验证」，说明规则已注入。

完整、可复制的「配置指令」见 docs/INIT-PROMPT.md。

多端生效

若所用工具支持云端同步全局规则（如 Trae 的账号全局规则），在电脑端配置一次后，手机端登录同一账号即可自动生效；项目内保留 AGENTS.md 及同步生成的工具文件，保证本地项目级规则也生效。

MCP 怎么配（通用，不绑定任何单一工具）

MCP（Model Context Protocol）让 AI 标准化直连外部系统（GitHub、数据库、Notion、文件系统），比临时拼命令行更稳更安全。但它需要常驻进程与权限，配置权在你手里：

• AI 禁止自下载、自安装、自启动、自配置 MCP（见 AGENTS.md §5 红线）。

• 你从 docs/skills/mcp-registry.md 挑选可信服务，按各工具的配置文件手动粘贴 mcp.example.json 里对应的 JSON（把 ${GITHUB_TOKEN} 等占位符换成你的环境变量）。

• 各工具配置位置：

  工具	配置文件路径
  Trae	.trae/mcp.json
  Claude Desktop	claude_desktop_config.json
  Cursor	.cursor/mcp.json
  VS Code	.vscode/mcp.json（或 settings.json 的 mcp 字段）

• Token / 密钥一律用环境变量注入，绝不硬编码进仓库。

安全与保密红线（节选）

• 绝对禁止把 API Key / Token / 密码硬编码进源代码，必须用 os.getenv() 或 python-dotenv 读取。
• 严禁把 .env 提交到 Git，确保其在 .gitignore。
• 拉取外部模板时禁止带入其 .git、LICENSE、README 等无关文件。
• 提交前必须 git status 检查意外文件；绝不自动 git push、绝不 git push -f、绝不盲目 git add .。

完整 8 节规则见 AGENTS.md。

修改规则（只动源头）

只编辑 AGENTS.md，然后运行同步脚本，工具专属文件会自动更新：

python scripts/sync_rules.py

脚本会把 AGENTS.md 中的 @引用 内联展开，重新生成 CLAUDE.md、GEMINI.md、.github/copilot-instructions.md。

迭代建议

每次发现 AI 重复犯同类错误，就把对应约束写回 AGENTS.md 并重跑同步——规则越用越准。本仓库自身也遵守这套铁律：所有交付都先规划、再实现、最后跑验证。