Files
lpt-meta/.agents/roles/README.md
T

4.3 KiB
Raw Blame History

通用规则(.agents/roles/)

存放跨仓库通用的代理行为规则。

目录名叫 roles,但里面不放「角色扮演」式定义(没有「你是某某角色、你的职责是……」), 只记录规则本身:什么情况下必须做什么、怎么核对。

放什么,不放什么

判断标准只有一句:这条规则换到另一个仓库还成立吗?

内容 位置 例子
通用规则(不限仓库) meta 仓库 .agents/roles/ 提交规范、调研汇报、并行委派
项目专属规则 各仓库自己的 .agents/roles/ 后端的迁移规范、前端的代码标准
项目知识与架构约定 各仓库 AGENTS.md 端口、调用关系、命名约定
跨仓库待办与验收标准 OPTIMIZATION_BACKLOG.md 优化条目
工作区级技能(共有技能唯一来源) meta .agents/skills/ mermaid-diagram、write-notes-like-deepseek
项目专属技能 各仓库自己的 .agents/skills/ lpt-be/.agents/skills/comment-cleanup

共有技能只在 meta 放一份,子项目内不建副本、不建符号链接;理由与验收见 .agents/roles/workspace-layout.md。

生效方式(重要)

.agents/roles/ 不是自动加载入口,任何 harness 都不会扫描它。 规则要真正约束行为,必须在 AGENTS.md 里被引用—— AGENTS.md 是各 harness 通用的项目指令入口(Claude 体系另有 CLAUDE.md),只有它会被读到。 所以:新增规则时,务必同时在该仓库 AGENTS.md 挂上入口,并在 meta AGENTS.md 的子仓库索引里登记路径与触发场景。

配套事实:

  • agent 会话从 meta 根目录启动,子项目靠 subagent(cwd=<repo>) 进入(见 meta AGENTS.md 首页)。因此共有技能放在 meta 就能被发现,不需要往子仓库复制。
  • 在子目录里启动 agent 时,父目录的 AGENTS.md 也会被读到(各 harness 大体一致),但这不是默认工作方式,不要依赖它:在 lpt-be 里启动看不到另外四个仓库的约定,也看不见 meta 的共有技能。
  • 反过来,在 meta 根目录干活时子仓库 AGENTS.md 不会自动加载,靠 meta 的子仓库索引带出。

规则文件的写法(强制)

每个规则文件的开头必须是如下三段,顺序不变,方便 agent 在决定是否继续读之前就能判断该不该用:

  1. 名称——作为 # 一级标题;
  2. 功能简述——一句话说明这条规则解决什么问题;
  3. 关键字 / 情况——告诉 agent 何时需要用到这条规则。这部分要简洁(一行枚举触发场景即可),不要在这里展开内容,正文放到后面。

模板:

# <名称>

- **功能**:<一句话说明这条规则做什么>
- **何时用**:<触发场景 / 关键字的简短枚举>

## <正文…>

新增或修改规则后自查:标题是名称?有「功能」行?有「何时用」行?「何时用」是否够短?

规则清单

规则 文件 何时用(触发点)
todo 收口纪律 todo-discipline.md 提交后 / 轮末 / 会话压缩后
并行与委派 parallel-and-delegation.md 开工排期、派发子任务时
子代理执行与复核 subagent-execution.md 改动面大、要拆多个单元执行时;复核子代理产出时
提交规范 commit-convention.md 写提交信息时
调研与问题定位 research-and-reporting.md 调研/排查/定位问题类任务
Windows / PowerShell 环境 shell-environment.md 执行 shell 命令、报错排查时
工作区资产归属 workspace-layout.md 决定文档/规则/技能放哪时
跨仓库 Git 操作 repo-operations.md 对子项目执行 git 命令时
开发环境自解锁与求助阈值 dev-unblock-and-escalation.md 被登录/权限/凭据卡住、同一问题反复尝试未解决时
业务名词收敛 business-terminology.md 描述系统概念、拆需求、派子代理、写笔记或提交信息时
图示优先的表达 visual-communication.md 汇报布局/流程/结构、做设计评审、回答「长什么样」时
说人话 plain-language.md 写回复、解释方案与取舍、写交付说明时;用户说「什么意思」「太复杂」时