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_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/command),UI 只呈现不复制逻辑——
|
||||
否则人与 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
|
||||
|
||||
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 是 agent 自验的唯一判断依据,必须是**可执行断言**,不能是描述性语句:
|
||||
|
||||
@ -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/command),UI 只呈现不复制逻辑——
|
||||
否则人与 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user