feat(onboarding): AGENTS 模板注入「同源同边界 + 操作复刻」设计原则(v1.7.0)
多角度辩证收敛后的 v3.1 外科手术版(真实增量三个半,不重复已有六条): - 节首总纲:任何功能 = 一个本体 + 两个投影,同源同边界;先定本体后盖投影(原型探索豁免) - 边界单点实现追加同源推论:人的操作序列 agent 皆可复刻,人报障即复现路径(操作+状态) - 三分定位启发式(本体→投影→环境),从"定律"降级——crypto.randomUUID 环境层实锤 - human_verify 否决理由值得记录(飞轮原料;采集机制挂 governance-feedback-loop,不空头承诺) - 炼境自身 AGENTS.md 块内同步 + agents-meta-rules.md 设计草案同步 Feature-Confirmed: true Rules-Applied: R13
This commit is contained in:
parent
1bb4ce978e
commit
9f468a13a1
11
AGENTS.md
11
AGENTS.md
@ -138,7 +138,7 @@ docs/templates/ 炼境接入包模板草案(设计层)
|
|||||||
完整规则(迭代管理、阻塞处理、复盘笔记等)详见 `.blueprint/CONVENTIONS.md`。
|
完整规则(迭代管理、阻塞处理、复盘笔记等)详见 `.blueprint/CONVENTIONS.md`。
|
||||||
<!-- BLUEPRINT_MANAGED_END -->
|
<!-- BLUEPRINT_MANAGED_END -->
|
||||||
|
|
||||||
<!-- ONBOARDING_MANAGED_START version="1.6.1" -->
|
<!-- ONBOARDING_MANAGED_START version="1.7.0" -->
|
||||||
> ⚠️ 本块由炼境版本化托管,升级时**整块原位覆盖**——项目定制请写到块外,块内手改必丢(2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示)。
|
> ⚠️ 本块由炼境版本化托管,升级时**整块原位覆盖**——项目定制请写到块外,块内手改必丢(2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示)。
|
||||||
|
|
||||||
## 核心开发约束
|
## 核心开发约束
|
||||||
@ -189,10 +189,14 @@ docs/templates/ 炼境接入包模板草案(设计层)
|
|||||||
## agent 按钮与验证路径
|
## agent 按钮与验证路径
|
||||||
|
|
||||||
功能的本体是代码层的能力;UI 按钮是它给人的投影,**agent 按钮**是给 agent 的投影
|
功能的本体是代码层的能力;UI 按钮是它给人的投影,**agent 按钮**是给 agent 的投影
|
||||||
(可发现 + 可调用 + 有边界的能力声明)。开发任何功能时遵守:
|
(可发现 + 可调用 + 有边界的能力声明)。**任何功能 = 一个本体 + 两个投影,同源同边界**;
|
||||||
|
设计交付时先定本体后盖投影(原型探索不受此序约束,交付前本体归位)。开发任何功能时遵守:
|
||||||
|
|
||||||
1. **边界单点实现**:业务校验只写在能力本体层(API/command),UI 只呈现不复制逻辑——
|
1. **边界单点实现**:业务校验只写在能力本体层(API/command),UI 只呈现不复制逻辑——
|
||||||
否则人与 agent 的验证路径会分裂
|
否则人与 agent 的验证路径会分裂。同源的直接推论:**人的操作序列 agent 皆可复刻**——
|
||||||
|
人报障即复现路径(操作 + 状态),agent 重放至同一状态定位病灶。
|
||||||
|
三分定位启发式:本体重放正常 → 优先怀疑投影层(接线/渲染/状态同步)→ 再查环境差异
|
||||||
|
(安全上下文/网络/OS);重放失败先怀疑初始状态差异,而非否定问题存在
|
||||||
2. **载体就近选择**(本项目的 agent 按钮是什么,按项目类型对号入座):
|
2. **载体就近选择**(本项目的 agent 按钮是什么,按项目类型对号入座):
|
||||||
| 项目类型 | agent 按钮载体 |
|
| 项目类型 | agent 按钮载体 |
|
||||||
|---------|---------------|
|
|---------|---------------|
|
||||||
@ -214,6 +218,7 @@ docs/templates/ 炼境接入包模板草案(设计层)
|
|||||||
- `agent_verify:` — 机器可断言(HTTP 状态码、数据库记录、函数返回值);stop hook / CI 只验此段
|
- `agent_verify:` — 机器可断言(HTTP 状态码、数据库记录、函数返回值);stop hook / CI 只验此段
|
||||||
- `human_verify:` — 需人眼判断(视觉效果、拖拽手势、30 秒浏览器终验)
|
- `human_verify:` — 需人眼判断(视觉效果、拖拽手势、30 秒浏览器终验)
|
||||||
纯 API / 命令行任务可省略 `human_verify:`;UI 拖拽 / 动画 / 视觉类必须拆,否则 stop hook 无法收敛。
|
纯 API / 命令行任务可省略 `human_verify:`;UI 拖拽 / 动画 / 视觉类必须拆,否则 stop hook 无法收敛。
|
||||||
|
human_verify 的否决理由值得记录——它是把体感转译成可断言规则的原料。
|
||||||
6. **自验报告纪律**:交人终验前的反馈必须含「**没验什么**」一节(未覆盖的路径、依赖的
|
6. **自验报告纪律**:交人终验前的反馈必须含「**没验什么**」一节(未覆盖的路径、依赖的
|
||||||
假设、不确定的地方);自修过程中改了断言/验收标准必须显式声明理由(改功能让测试过是
|
假设、不确定的地方);自修过程中改了断言/验收标准必须显式声明理由(改功能让测试过是
|
||||||
常规,改测试让功能过需报备);agent 自验对 acceptance,人终验对意图——acceptance
|
常规,改测试让功能过需报备);agent 自验对 acceptance,人终验对意图——acceptance
|
||||||
|
|||||||
6
docs/templates/agents-meta-rules.md
vendored
6
docs/templates/agents-meta-rules.md
vendored
@ -109,6 +109,12 @@ AGENTS.md 或 `docs/ai-context/project-brief.md` 描述的现实已经改变。
|
|||||||
|
|
||||||
三要素缺一不可:**可发现**(清单里有)、**可调用**(结构化命令)、**边界清晰**(通过标准明确)。
|
三要素缺一不可:**可发现**(清单里有)、**可调用**(结构化命令)、**边界清晰**(通过标准明确)。
|
||||||
|
|
||||||
|
### 同源同边界(设计原则,v1.7.0 起)
|
||||||
|
|
||||||
|
**任何功能 = 一个本体 + 两个投影**:本体是能力层实现(API/command/服务函数),人按钮(UI)与 agent 按钮都是它的投影。同源 = 两投影走同一代码路径;同边界 = 业务校验只在本体层砌一次墙。设计交付时先定本体后盖投影(原型探索豁免此序,交付前本体归位)。
|
||||||
|
|
||||||
|
同源的直接推论:**人的操作序列 agent 皆可复刻**——人报障即复现路径(操作 + 状态),agent 重放至同一状态定位病灶。三分定位启发式:本体重放正常 → 优先怀疑投影层 → 再查环境差异;重放失败先怀疑初始状态差异,而非否定问题存在。
|
||||||
|
|
||||||
### Acceptance 写法规范
|
### Acceptance 写法规范
|
||||||
|
|
||||||
acceptance 是 agent 自验的唯一判断依据,必须是**可执行断言**,不能是描述性语句:
|
acceptance 是 agent 自验的唯一判断依据,必须是**可执行断言**,不能是描述性语句:
|
||||||
|
|||||||
@ -18,7 +18,7 @@
|
|||||||
|
|
||||||
<!-- TODO: 列出 README / ARCHITECTURE.md / 其他关键文档及用途。 -->
|
<!-- TODO: 列出 README / ARCHITECTURE.md / 其他关键文档及用途。 -->
|
||||||
|
|
||||||
<!-- ONBOARDING_MANAGED_START version="1.6.1" -->
|
<!-- ONBOARDING_MANAGED_START version="1.7.0" -->
|
||||||
> ⚠️ 本块由炼境版本化托管,升级时**整块原位覆盖**——项目定制请写到块外,块内手改必丢(2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示)。
|
> ⚠️ 本块由炼境版本化托管,升级时**整块原位覆盖**——项目定制请写到块外,块内手改必丢(2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示)。
|
||||||
|
|
||||||
## 核心开发约束
|
## 核心开发约束
|
||||||
@ -69,10 +69,14 @@
|
|||||||
## agent 按钮与验证路径
|
## agent 按钮与验证路径
|
||||||
|
|
||||||
功能的本体是代码层的能力;UI 按钮是它给人的投影,**agent 按钮**是给 agent 的投影
|
功能的本体是代码层的能力;UI 按钮是它给人的投影,**agent 按钮**是给 agent 的投影
|
||||||
(可发现 + 可调用 + 有边界的能力声明)。开发任何功能时遵守:
|
(可发现 + 可调用 + 有边界的能力声明)。**任何功能 = 一个本体 + 两个投影,同源同边界**;
|
||||||
|
设计交付时先定本体后盖投影(原型探索不受此序约束,交付前本体归位)。开发任何功能时遵守:
|
||||||
|
|
||||||
1. **边界单点实现**:业务校验只写在能力本体层(API/command),UI 只呈现不复制逻辑——
|
1. **边界单点实现**:业务校验只写在能力本体层(API/command),UI 只呈现不复制逻辑——
|
||||||
否则人与 agent 的验证路径会分裂
|
否则人与 agent 的验证路径会分裂。同源的直接推论:**人的操作序列 agent 皆可复刻**——
|
||||||
|
人报障即复现路径(操作 + 状态),agent 重放至同一状态定位病灶。
|
||||||
|
三分定位启发式:本体重放正常 → 优先怀疑投影层(接线/渲染/状态同步)→ 再查环境差异
|
||||||
|
(安全上下文/网络/OS);重放失败先怀疑初始状态差异,而非否定问题存在
|
||||||
2. **载体就近选择**(本项目的 agent 按钮是什么,按项目类型对号入座):
|
2. **载体就近选择**(本项目的 agent 按钮是什么,按项目类型对号入座):
|
||||||
| 项目类型 | agent 按钮载体 |
|
| 项目类型 | agent 按钮载体 |
|
||||||
|---------|---------------|
|
|---------|---------------|
|
||||||
@ -94,6 +98,7 @@
|
|||||||
- `agent_verify:` — 机器可断言(HTTP 状态码、数据库记录、函数返回值);stop hook / CI 只验此段
|
- `agent_verify:` — 机器可断言(HTTP 状态码、数据库记录、函数返回值);stop hook / CI 只验此段
|
||||||
- `human_verify:` — 需人眼判断(视觉效果、拖拽手势、30 秒浏览器终验)
|
- `human_verify:` — 需人眼判断(视觉效果、拖拽手势、30 秒浏览器终验)
|
||||||
纯 API / 命令行任务可省略 `human_verify:`;UI 拖拽 / 动画 / 视觉类必须拆,否则 stop hook 无法收敛。
|
纯 API / 命令行任务可省略 `human_verify:`;UI 拖拽 / 动画 / 视觉类必须拆,否则 stop hook 无法收敛。
|
||||||
|
human_verify 的否决理由值得记录——它是把体感转译成可断言规则的原料。
|
||||||
6. **自验报告纪律**:交人终验前的反馈必须含「**没验什么**」一节(未覆盖的路径、依赖的
|
6. **自验报告纪律**:交人终验前的反馈必须含「**没验什么**」一节(未覆盖的路径、依赖的
|
||||||
假设、不确定的地方);自修过程中改了断言/验收标准必须显式声明理由(改功能让测试过是
|
假设、不确定的地方);自修过程中改了断言/验收标准必须显式声明理由(改功能让测试过是
|
||||||
常规,改测试让功能过需报备);agent 自验对 acceptance,人终验对意图——acceptance
|
常规,改测试让功能过需报备);agent 自验对 acceptance,人终验对意图——acceptance
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user