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:
lanrtop 2026-08-23 16:31:30 +09:00
parent 1bb4ce978e
commit 9f468a13a1
3 changed files with 22 additions and 6 deletions

View File

@ -138,7 +138,7 @@ docs/templates/ 炼境接入包模板草案(设计层)
完整规则(迭代管理、阻塞处理、复盘笔记等)详见 `.blueprint/CONVENTIONS.md`
<!-- BLUEPRINT_MANAGED_END -->
<!-- ONBOARDING_MANAGED_START version="1.6.1" -->
<!-- ONBOARDING_MANAGED_START version="1.7.0" -->
> ⚠️ 本块由炼境版本化托管,升级时**整块原位覆盖**——项目定制请写到块外块内手改必丢2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示)。
## 核心开发约束
@ -189,10 +189,14 @@ docs/templates/ 炼境接入包模板草案(设计层)
## agent 按钮与验证路径
功能的本体是代码层的能力UI 按钮是它给人的投影,**agent 按钮**是给 agent 的投影
(可发现 + 可调用 + 有边界的能力声明)。开发任何功能时遵守:
(可发现 + 可调用 + 有边界的能力声明)。**任何功能 = 一个本体 + 两个投影,同源同边界**
设计交付时先定本体后盖投影(原型探索不受此序约束,交付前本体归位)。开发任何功能时遵守:
1. **边界单点实现**业务校验只写在能力本体层API/commandUI 只呈现不复制逻辑——
否则人与 agent 的验证路径会分裂
否则人与 agent 的验证路径会分裂。同源的直接推论:**人的操作序列 agent 皆可复刻**——
人报障即复现路径(操作 + 状态agent 重放至同一状态定位病灶。
三分定位启发式:本体重放正常 → 优先怀疑投影层(接线/渲染/状态同步)→ 再查环境差异
(安全上下文/网络/OS重放失败先怀疑初始状态差异而非否定问题存在
2. **载体就近选择**(本项目的 agent 按钮是什么,按项目类型对号入座):
| 项目类型 | agent 按钮载体 |
|---------|---------------|
@ -214,6 +218,7 @@ docs/templates/ 炼境接入包模板草案(设计层)
- `agent_verify:` — 机器可断言HTTP 状态码、数据库记录、函数返回值stop hook / CI 只验此段
- `human_verify:` — 需人眼判断视觉效果、拖拽手势、30 秒浏览器终验)
纯 API / 命令行任务可省略 `human_verify:`UI 拖拽 / 动画 / 视觉类必须拆,否则 stop hook 无法收敛。
human_verify 的否决理由值得记录——它是把体感转译成可断言规则的原料。
6. **自验报告纪律**:交人终验前的反馈必须含「**没验什么**」一节(未覆盖的路径、依赖的
假设、不确定的地方);自修过程中改了断言/验收标准必须显式声明理由(改功能让测试过是
常规改测试让功能过需报备agent 自验对 acceptance人终验对意图——acceptance

View File

@ -109,6 +109,12 @@ AGENTS.md 或 `docs/ai-context/project-brief.md` 描述的现实已经改变。
三要素缺一不可:**可发现**(清单里有)、**可调用**(结构化命令)、**边界清晰**(通过标准明确)。
### 同源同边界设计原则v1.7.0 起)
**任何功能 = 一个本体 + 两个投影**本体是能力层实现API/command/服务函数人按钮UI与 agent 按钮都是它的投影。同源 = 两投影走同一代码路径;同边界 = 业务校验只在本体层砌一次墙。设计交付时先定本体后盖投影(原型探索豁免此序,交付前本体归位)。
同源的直接推论:**人的操作序列 agent 皆可复刻**——人报障即复现路径(操作 + 状态agent 重放至同一状态定位病灶。三分定位启发式:本体重放正常 → 优先怀疑投影层 → 再查环境差异;重放失败先怀疑初始状态差异,而非否定问题存在。
### Acceptance 写法规范
acceptance 是 agent 自验的唯一判断依据,必须是**可执行断言**,不能是描述性语句:

View File

@ -18,7 +18,7 @@
<!-- TODO: 列出 README / ARCHITECTURE.md / 其他关键文档及用途。 -->
<!-- ONBOARDING_MANAGED_START version="1.6.1" -->
<!-- ONBOARDING_MANAGED_START version="1.7.0" -->
> ⚠️ 本块由炼境版本化托管,升级时**整块原位覆盖**——项目定制请写到块外块内手改必丢2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示)。
## 核心开发约束
@ -69,10 +69,14 @@
## agent 按钮与验证路径
功能的本体是代码层的能力UI 按钮是它给人的投影,**agent 按钮**是给 agent 的投影
(可发现 + 可调用 + 有边界的能力声明)。开发任何功能时遵守:
(可发现 + 可调用 + 有边界的能力声明)。**任何功能 = 一个本体 + 两个投影,同源同边界**
设计交付时先定本体后盖投影(原型探索不受此序约束,交付前本体归位)。开发任何功能时遵守:
1. **边界单点实现**业务校验只写在能力本体层API/commandUI 只呈现不复制逻辑——
否则人与 agent 的验证路径会分裂
否则人与 agent 的验证路径会分裂。同源的直接推论:**人的操作序列 agent 皆可复刻**——
人报障即复现路径(操作 + 状态agent 重放至同一状态定位病灶。
三分定位启发式:本体重放正常 → 优先怀疑投影层(接线/渲染/状态同步)→ 再查环境差异
(安全上下文/网络/OS重放失败先怀疑初始状态差异而非否定问题存在
2. **载体就近选择**(本项目的 agent 按钮是什么,按项目类型对号入座):
| 项目类型 | agent 按钮载体 |
|---------|---------------|
@ -94,6 +98,7 @@
- `agent_verify:` — 机器可断言HTTP 状态码、数据库记录、函数返回值stop hook / CI 只验此段
- `human_verify:` — 需人眼判断视觉效果、拖拽手势、30 秒浏览器终验)
纯 API / 命令行任务可省略 `human_verify:`UI 拖拽 / 动画 / 视觉类必须拆,否则 stop hook 无法收敛。
human_verify 的否决理由值得记录——它是把体感转译成可断言规则的原料。
6. **自验报告纪律**:交人终验前的反馈必须含「**没验什么**」一节(未覆盖的路径、依赖的
假设、不确定的地方);自修过程中改了断言/验收标准必须显式声明理由(改功能让测试过是
常规改测试让功能过需报备agent 自验对 acceptance人终验对意图——acceptance