AI 编程助手规则文件怎么写：项目约定与禁止项（2026）

摘要：按 Cursor Rules、GitHub Copilot 仓库自定义指令、Claude Code CLAUDE.md / AGENTS.md 官方文档，整理规则文件放哪、写什么项目约定、哪些禁止项该写进文件，以及怎么自检是否生效。只放官网普通链接；不写套餐价。

依据：Cursor Docs《Rules》、GitHub Docs《Adding repository custom instructions for GitHub Copilot》、Claude Code Docs《How Claude remembers your project》。查询日期：2026-10-28（北京时间）。功能名、路径与套餐因产品改版而异，以你当前客户端与帮助页为准。本文只放官网普通链接（affiliate_later）。不构成安全审计或法律意见；密钥、生产数据仍按你们现有合规流程处理。

本站已有AI 编程工具怎么选（偏选型与数据设置）和用 AI 写正则与 SQL（偏单次提示约束）。本文收窄到一件事：怎么把「项目约定」和「禁止项」写进规则文件，让助手在每次对话里都能读到，而不是靠你口头重复。

提示词四段骨架见提示词怎么写；哪些内容别往对话框里贴，见AI 工具的数据隐私。

一、先认清：规则文件解决什么问题

大模型单次对话之间默认不记「你们仓库的规矩」。Cursor 文档写明：规则会在适用时被放进模型上下文开头，用来统一生成代码、解释改动的方式。Claude Code 文档则把 CLAUDE.md / AGENTS.md 写成「你写的持久说明」，和「Claude 自己记的 auto memory」分开。

实操上，规则文件适合写这些：

适合写进规则	不适合硬塞进规则
构建 / 测试 / lint 命令与顺序	整本风格指南（交给 linter / formatter）
目录约定、权威示例文件路径	极少发生的边角例外
禁止改的目录、禁止提交的密钥形态	与本次任务无关的长教程全文
接口错误返回格式、命名习惯	把 README 整页复制一遍

Cursor 文档的建议是：短、可执行、能指向仓库里的权威示例；看到助手反复犯同一错再补一条，而不是一上来写几百行。

AI 编程助手规则文件怎么写：项目约定与禁止项（2026）-有序 — Cursor 官方文档：Project Rules、User Rules、Team Rules 与 AGENTS.md 四类规则（2026-10-28 截图）

二、三家常见落点（路径对照）

下面按官方帮助页整理「仓库级」落点；个人全局偏好另说。

1. Cursor

项目规则：.cursor/rules/*.mdc（须 .mdc；纯 .md 放在该目录会被忽略）。可用 frontmatter 控制 alwaysApply、description、globs。
AGENTS.md：仓库根或子目录的纯 Markdown；无 frontmatter，靠目录位置限定范围；嵌套时更具体的说明优先。
用户规则：Customize → Rules，跨项目。
团队规则：Team / Enterprise 仪表盘；与项目规则并存时，官方写明优先级为 Team → Project → User。

2. GitHub Copilot（仓库自定义指令）

按 GitHub Docs 当前说明，仓库侧常见三类：

全仓：.github/copilot-instructions.md
按路径：.github/instructions/NAME.instructions.md，文首 YAML 里写 applyTo glob（可多模式逗号分隔）
Agent 说明：仓库内任意位置的 AGENTS.md（就近优先）；也可在根目录用单个 CLAUDE.md 或 GEMINI.md

路径级与全仓同时存在时，官方写明两者都会用上。个人指令、仓库指令、组织指令可以叠加；冲突时尽量避免互相打架。

3. Claude Code

项目说明：./CLAUDE.md 或 ./.claude/CLAUDE.md；也可用 AGENTS.md（无 CLAUDE.md 时默认可读 AGENTS.md，细节以 /config 里 Project instructions 为准）。
个人项目偏好：CLAUDE.local.md（建议 gitignore）。
按路径规则：.claude/rules/*.md，可用 paths frontmatter 限定文件。
Auto memory：Claude 自己写的笔记，和你手写的 CLAUDE.md 互补；文档提醒 CLAUDE.md 是「上下文指导」，硬性拦截仍要用 hook / 权限设置。

多人协作时，把「团队要共同遵守」的写进可提交的项目文件；把本机沙箱 URL、私人测试账号写进 local / user 层。

三、项目约定：建议写清的字段

可以直接当草稿骨架（按需删减）：

# 项目说明（给编程助手）

## 这是什么
- 一句话：产品做什么、主要语言与运行时

## 常用命令（按顺序）
- 安装：…
- 构建：…
- 单测：…（优先单个文件，避免默认全仓）
- Lint / 类型检查：…

## 目录与权威示例
- 新 API 放在：`src/…`
- 组件写法看：`components/Button.tsx`
- 不要改：`dist/`、`vendor/`、生成代码目录

## 接口与错误
- 对外错误返回：`{ "code": "…", "message": "…" }`
- 日志禁止打印：密码、token、完整身份证号

## 提交前
- 改完相关模块后跑：…（写你们真实命令）

写命令时用「总是先 npm install 再 build」这类可核对句子，比「注意环境」更管用。Claude Code 文档举例：「Use 2-space indentation」「Run npm test before committing」「API handlers live in src/api/handlers/」。

四、禁止项：建议单独成节

禁止项写进规则，是为了减少「助手好心改坏」和「密钥进对话」：

密钥与凭据：禁止新建或提交 .env 真值、私钥、生产数据库连接串；需要示例时只用占位符。
范围外改动：禁止顺手重构无关目录；禁止改 lockfile，除非任务明确要求。
危险操作：禁止 git push --force 到共享主分支；禁止在未确认时删除迁移 / 生产配置。
依赖与许可：禁止擅自加入 GPL 等你们政策不允许的许可证依赖（写你们实际政策）。
数据外传：禁止把客户全量数据、未公开合同粘进公有云对话；细则见数据隐私。
测试造假：禁止为了「变绿」而删除断言或跳过 CI 必需步骤。

禁止项要写「具体动作」，少写「注意安全」这类空话。需要强制拦截时，Cursor / Claude Code 都另有钩子、权限拒绝列表；规则文件 alone 不能当唯一闸门。

五、落地顺序与自检

先开一个文件：Cursor 用一条 alwaysApply 短规则或根目录 AGENTS.md；Copilot 用 .github/copilot-instructions.md；Claude Code 用 /init 生成草稿再改。
只写本周反复踩过的 5–10 条。
新开对话，让助手「复述本仓库构建命令与禁止改动的目录」；对不上就改文件，而不是只在聊天里骂一句。
Cursor：确认规则类型（Always / globs / 手动 @）；Copilot：看回复引用列表里是否出现指令文件；Claude Code：用 /context 或 /memory 看 Memory files。
大仓再拆：前端 / 后端分文件 + glob / paths / 嵌套 AGENTS.md，避免一条 Always 塞满上下文。

助手仍可能幻觉接口或漏读规则。改完关键逻辑，按幻觉核查清单自己跑测试与 diff，不要只看「看起来像对」。

六、和本站其它文怎么配合

还在选型：先看编程工具怎么选。
单次任务提示：用四段提示词框架，约束段可写「遵守仓库 AGENTS.md / CLAUDE.md」。
长文档核对：见读长 PDF。

风险与说明

规则是上下文指导，不是操作系统级强制；敏感操作仍要人工审 diff、审 CI。
产品路径与字段名会改版；以查询日之后你打开的官方文档为准。
不要把生产密钥写进规则文件再提交到公开仓库。
本文不评价各产品优劣，也不提供付费套餐价格。

AI 编程助手规则文件怎么写：项目约定与禁止项（2026）

一、先认清：规则文件解决什么问题