agents-md-setup

name	agents-md-setup
description	`AGENTS.md` 是 P-AI 自动读取的项目级编码协作约束；当它缺失，或内容已经明确过期、与当前项目现状冲突时，必须立刻阅读我，理解如何生成或更新它。

AGENTS.md Setup

核心目标

• AGENTS.md 是项目级的编码协作约束，不是随便补一份占位说明。
• 只有在你已经进入一个明确的项目目录，并准备持续做编程工作时，才处理它。
• 默认工作区、临时 scratch 目录、一次性小实验，不要因为缺少 AGENTS.md 就强行生成。
• 如果已有 AGENTS.md，先把它当作现有草稿，与当前仓库事实和用户要求一起重新整理。

先做项目审查，再写

• 先确认项目根目录，不要把子目录误当根目录。
• 至少阅读这些真实文件，再决定怎么写：
  • README.md
  • 构建与依赖文件，如 package.json、pnpm-lock.yaml、Cargo.toml、pyproject.toml、go.mod
  • 测试与构建配置，如 vite.config.*、vitest.config.*、tsconfig.json、tauri.conf.json
  • 协作与规范文件，如 CONTRIBUTING.md、现有 AGENTS.md
  • 能帮助识别架构的关键入口文件和主要目录
• 如果命令、目录、模块边界没有从仓库里核实，就不要写进 AGENTS.md。

生成方式

• 默认采用本项目这份 AGENTS.md 的组织方式，但内容必须按目标项目裁剪。
• 不要按“补一段缺失说明”的思路零碎修修补补；应按结构域重写成一份完整、当前可执行的项目规则。
• 如果旧 AGENTS.md 中有仍然正确的内容，可以吸收进新结构；不要把新旧冲突规则并列保留。
• 语言以用户语言为准。

推荐结构

• # AGENTS.md
• ## 项目概述
• ## 构建与开发命令
• ## 架构概览
• ## 关键目录与数据流
• ## 开发约定
• ## 测试与验证要求
• ## 提交与发布规则
• ## 项目特有流程

不是每个项目都必须有全部章节；没有真实依据的章节宁可不写。

按结构域生成

项目概述

• 用 3 到 8 行写清项目是什么、主要面向什么平台、主要技术栈是什么。
• 如果项目有明显发布对象，也写出来，例如 Web / Windows / Linux / 桌面端 / 服务端。
• 只写项目级事实，不要写空泛目标。

构建与开发命令

• 从真实脚本和配置文件提取最常用命令。
• 优先写开发、构建、类型检查、测试、发布这几类。
• 命令要能直接复制运行，不要写伪命令。
• 如果前后端命令分目录，明确写出在哪个目录执行。

架构概览

• 用当前仓库真实结构解释主要模块怎么分工。
• 优先写真正影响编码落点的边界，比如：
  • 前后端边界
  • 核心入口文件
  • 状态管理方式
  • 关键目录对应的职责
• 不要展开成设计文档，只写后续编码时必须知道的组织方式。

关键目录与数据流

• 当项目目录较多、数据流明显时再写。
• 适合写：
  • 配置文件在哪里
  • 运行数据在哪里
  • 资源目录在哪里
  • 代码从哪里进入、往哪里流
• 如果项目简单，没有必要单独凑一节。

开发约定

• 这里写语言、框架、样式、模块拆分、日志、注释、错误处理等规则。
• 要写成“后续编码时的硬约束”，不要写成介绍。
• 如果是多语言项目，按 Rust / 前端 / Python 之类分小节写。
• 只有项目里真实存在的规则才写进去。
• 写法优先服务 AI 后续开发与协作，不要优先迎合“给人类看着舒服”的文档风格。
• 对能直接约束后续编码决策的规则，优先写得短、硬、可执行。
• 日志标准默认以用户语言优先，除非项目里已有更明确的既有约定。
• 如果是新项目，或仓库里没有更明确的组织约定，默认采用“紧凑优先”起步，并在边界清晰后转向“按功能组织（优先使用垂直切分结构）”。

测试与验证要求

• 写提交前至少要跑什么。
• 写开发过程中应该怎么边改边测，而不是只在最后一次性跑。
• 如果有“先跑定向，再跑全量”或“改前端只跑前端相关集”这类项目习惯，也写清楚。
• 如果仓库已有用户明确要求，优先写进去。

提交与发布规则

• 写 commit message 风格、版本号同步位置、发布前检查项、不能做的危险操作。
• 如果要写提交规范，适度参考最近几条 commit 的真实风格，再总结类型、scope、语言习惯；不要凭空发明一套和仓库历史脱节的提交规范。
• 如果项目没有发布流程，就只写提交规则，不要硬凑发布章节。

项目特有流程

• 只写这个项目独有、下一轮编码很可能踩坑的东西。
• 例如：
  • 计划文档必须先确认
  • 归档流程怎么走
  • 特殊生成文件怎么处理
  • 哪些目录不能乱动
• 没有项目特有流程就不要写。

与项目原生约定共存

• 先判断项目是否已经有自己的协作约定承载方式，例如其他 agent instruction 文件、团队规范文件、框架约定目录或仓库内固定规则文件。
• 如果项目明确已经使用别的原生约定文件来承载同类规则，不要硬把两套规则长期并存。
• 在这种情况下，如果仍需要临时生成本文件供当前环境读取，应把本文件加入 .gitignore，避免把它误提交进仓库，和项目原生约定形成双轨冲突。
• 只有当用户明确要求把 AGENTS.md 纳入仓库，或仓库本身已经接受这种文件作为正式约定时，才保留为版本化文件。

写作标准

• 只写对后续编码真的有帮助的规则。
• 优先写“这个项目特有、模型不容易自己猜到”的内容。
• 用明确命令、明确路径、明确目录名，不要写空话。
• 尽量写“应该做什么 / 不要做什么”，不要写泛泛背景介绍。
• 对高风险事项写硬规则，比如：
  • 先跑什么测试
  • 不能改哪些文件
  • 版本号需要同步哪些地方
  • 发布时必须检查什么
• 如果要写提交规范，适度参考最近几条 commit 的真实风格，再总结类型、scope、语言习惯；不要凭空发明一套和仓库历史脱节的提交规范。
• 不要写和仓库无关的通用鸡汤。

最小生成套路

1. 确认项目根目录。
2. 阅读真实构建、测试、架构文件。
3. 按结构域整理项目事实：
   • 项目概述
   • 构建与开发命令
   • 架构概览
   • 开发约定
   • 测试与验证要求
   • 提交与发布规则
   • 项目特有流程
4. 生成或重整 AGENTS.md。
5. 回头自检：
   • 命令能否在仓库中找到依据
   • 路径是否真实存在
   • 规则是否和当前代码组织一致
   • 是否和用户最新要求冲突

自检问题

• 我写进去的命令，仓库里真的能跑吗？
• 我写进去的架构分层，仓库里真的存在吗？
• 我是不是把别的项目的经验复制进来了？
• 这份 AGENTS.md 会帮助下一个编码轮次，还是只是在堆文档？
• 如果用户现在继续让我编码，这份 AGENTS.md 能不能直接指导我下一步怎么做？

输出

• 说明你是“新建”还是“更新”了 AGENTS.md。
• 说明你依据了哪些项目文件。
• 说明你修正了哪些过时或冲突规则。
• 如果你判断当前场景不该生成，也要明确说出原因。