notes

AI 自动落地规约：架构决策（ADR）与业务 Notes 机制自举执行协议

【系统最高指令】
当你（AI 智能体）读取到本规约时，本文件即为你当前任务的最高执行协议（SOP）。
你不需要等待用户发出进一步的细分指令，必须立即、自主、严格按照下述 Phase 1 至 Phase 7 的顺序自驱推进，在当前代码仓库中完整实现并落地整套 Notes 机制。

阶段一：工程特征逆向探测（Phase 1: Inspection & Profiling）

你必须首先调用文件搜索与读取工具，自主扫描当前代码库，获取落地所需的元数据（严禁凭空编造配置）：

单仓 vs 多仓拓扑判断：
- 检查根目录是否存在多个子系统独立目录（如包含独立的 package.json、pom.xml、go.mod、Cargo.toml 等）；
- 若为单仓：直接在根目录实施；
- 若为多仓/多模块：针对各子模块分别建立或在总工程中建立分层映射。
技术栈与构建指令探查：
- 前端：读取 package.json，提取包名、Vue/React 版本、构建工具（Vite/Webpack）、scripts 中的 lint、build、test 命令；
- 后端：读取 pom.xml、build.gradle、go.mod 等，提取语言版本、Spring Boot/Gin 等框架版本、针对性编译（如 Maven 单模块编译）命令；
- 数据库/持久层：扫描实体目录（entity/、models/）与 SQL 目录（migrations/、sql/），提取表前缀与持久层框架（MyBatis-Plus、JPA、GORM、Prisma 等）。
识别高频业务领域（至少提炼 2~4 个业务关键词）：
- 扫描业务层（service/、controller/、views/、api/），找出系统中最核心的业务实体名称（例如：order、customer、payment、appointment、inventory 等）。

阶段二：生成工程入口宪法（Phase 2: Generate CLAUDE.md & AGENTS.md）

你必须根据 Phase 1 探测到的真实信息，在仓库根目录创建或全量覆盖写入以下两个核心入口文件：

2.1 写入 `CLAUDE.md`（极简启动引导桩，严格控制在 30~50 行）

直接调用文件写入工具，在根目录创建 CLAUDE.md：

# CLAUDE.md

> **Single Source of Truth（唯一权威真理单源）**：
> 本工程的所有架构分层、分支基线、极速构建指令、编码防御模式、开发作业流水线及 **Agent Notes 双维知识库作业契约**已完整统合至 **[AGENTS.md](./AGENTS.md)**。

AI 智能体在当前代码库启动会话时，**必须立即读取并严格遵守 [AGENTS.md](./AGENTS.md) 作为最高执行准则**。严禁在此文件中维护重复规则以防双份文档漂移。

---

## 核心速查与安全铁律

1. **三跳按需读取**：处理非琐碎任务前，必须按 `AGENTS.md` 契约检索 `.agents/notes/README.md`，精准阅读 1~2 篇 ADR 后再编码；
2. **严禁硬编码密钥**：严禁向 Git 提交真实的 API Key、数据库密码、私钥证书等任何凭据；
3. **分支基线对齐**：必须在 `AGENTS.md` 规定的开发分支上作业，严禁向受保护主干直接 push；
4. **轻量针对性验证**：仅运行针对性编译或 Lint，严禁盲目执行耗时全量打包。

2.2 写入 `AGENTS.md`（工程最高宪法，必须完整填充 8 大板块）

根据 Phase 1 提取的真实数据填充各节，严禁留下 TODO 或空占位符：

# AGENTS.md — 工程全栈协同开发权威指南（Master Guide）

本指南为当前工程的跨智能体权威协同准则。所有 AI 智能体在当前代码库作业时，**必须无条件严格遵守**。

---

## 1. 工程定位与服务拓扑（Topology）
- **工程定位**：<基于 Phase 1 探测结果填入实际业务定位>
- **核心技术栈**：<填入 Phase 1 提取的具体语言、框架版本>
- **目录拓扑说明**：
  - `<核心源码目录>`: 职责说明
  - `<配置目录>`: 职责说明
  - `<测试目录>`: 职责说明

---

## 2. Git 分支基线与提交红线（Git Baseline & Red Lines）
| 分支名称 | 角色定位 | 派生与合入目标 | 绝对禁止项 |
|---|---|---|---|
| `main` / `master` | 生产稳定主干 | 仅允许通过 PR/评审合入 | 严禁直接 push |
| `dev` | 日常开发基线 | 从此切 feature，测试完成后合回 | 严禁跨环境错合 |

---

## 3. 针对性极速构建与轻量验证指令（Targeted Commands）
<!-- 必须填入 Phase 1 提取的真实有效命令，单次执行耗时控制在 30 秒以内 -->
```sh
# 1. 语法检查 / 静态检查
<填入当前项目的 lint 命令>

# 2. 局部快速编译（跳过无关打包与单测）
<填入当前项目的快速编译命令>

# 3. 针对性单元测试（指定单个用例文件）
<填入当前项目的单测执行示例命令>

4. 架构分层与核心编码契约（Architecture Conventions）

分层职责：控制层只处理入参校验与协议转换，业务逻辑沉淀服务层，持久层禁止不安全拼接；
统一响应与异常处理：全局统一包装类，严禁吞噬异常堆栈；
传输对象与实体解耦：数据库实体严禁直接穿透至外部请求返回；
事务边界控制：数据库事务内禁止包含外部第三方网络 IO（如外部支付调用、短信发送、大文件上传）。

5. 防御式编码模式（Defensive Patterns）

空安全防护：前置拦截非法参数，深层调用链防范空指针；
并发与幂等：核心写操作、支付扣费、状态机推进必须具备并发锁或防重拦截；
软删除唯一索引防冲突：采用逻辑删除时必须具备时间戳或状态避让机制；
金融高精度计算：货币与金额计算严禁直接使用原生浮点数除法，必须使用高精度对象或整数分存储。

6. 环境配置与密钥安全（Secrets & Config）

严禁向代码仓库提交任何真实生产密码、Token、AK/SK；
配置项使用环境变量或占位符解耦。

7. Agent Notes 双维知识库与三跳按需读取契约（Agent Notes Contract）

本仓库已建立基于 .agents/notes/ 的架构与业务知识底座：

目录拓扑：包含技术架构支线（architecture/）与业务领域主线（<biz-modules>/）；
三跳按需读取协议（Three-Hop Protocol）：
1. 第 1 跳：阅读本 AGENTS.md 掌握工程全局红线（已完成）；
2. 第 2 跳：处理具体需求前，必须先读 .agents/notes/README.md 大地图，毫秒级定位目标 Note；
3. 第 3 跳：仅阅读精准相关的 1~2 篇 Note，吸收历史事故与【切斯特顿之栅（被否决方案）】后再动手写代码；
代码与文档强同步契约：
- 凡新增模块、修改表结构、调整状态机、修改计算公式，必须在同一提交中更新或新建 Note；
- 重构导致类名、路径、接口变动，必须同步修正对应 Note 中的代码落地点；
- 漏更 Note 在代码审查中一票否决。

8. 全流程标准开发作业流水线（Development Pipeline）

[ 1. 需求分析与三跳读取 ] ──► 查 notes/README.md ──► 读目标 Note 掌握历史约束
             │
             ▼
[ 2. 方案编码与轻量验证 ] ──► 遵循编码契约 ──► 执行针对性 Lint / 快速编译
             │
             ▼
[ 3. 代码与 Note 同步回写 ] ──► 更新对应 Note 事实 ──► 刷新 notes/README.md 条目
             │
             ▼
[ 4. 提交前自检与发起 PR ] ──► 核对 git status ──► 确认代码与 Note 均已暂存 ──► 提交

---

## 阶段三：创建物理目录拓扑（Phase 3: Directory Setup）

你必须调用工具在仓库中创建以下目录骨架：

```text
.agents/
└── notes/
    ├── architecture/           # 必须创建：技术架构支线
    ├── <biz-module-1>/         # 必须创建：基于 Phase 1 发现的核心业务域命名
    └── <biz-module-2>/         # 必须创建：基于 Phase 1 发现的第二核心业务域命名

阶段四：逆向抽取首批基线 Note（Phase 4: Reverse-Engineer Initial ADRs）

你绝对不能保留空目录，必须深入代码，使用六大固定章节提炼至少 2 篇真实 ADR 并写入物理文件：

4.1 提取 1 篇系统技术架构 ADR

目标路径：.agents/notes/architecture/YYYY-MM-DD-tech-<slug>.md
抽取逻辑：阅读当前工程的一个关键底层实现（例如：全局异常捕获、JWT/Token 认证鉴权拦截器、多租户拦截、BaseEntity 自动填充或数据库事务切面）；
撰写要求：必须严格遵循 4.3 节的六大固定段落。

4.2 提取 1 篇核心业务领域 ADR

目标路径：.agents/notes/<biz-module-1>/YYYY-MM-DD-biz-<slug>.md
抽取逻辑：阅读最核心的一个业务 Service 或视图组件，分析其状态枚举（Status Enum）与业务规则；
撰写要求：必须画出 ASCII 状态机流转图，并记录边界约束。

4.3 单篇 Note 必填结构规范（严格执行六大段落）

# Agent Note: [功能/机制名称] [核心技术或业务特征概括]

Status: implemented

## 1. 业务本质 / 架构本质与反直觉设计动因（The Deep "Why"）
<!-- 解释表象之下的深层矛盾、反直觉考量，说明为什么简单的写法会出问题 -->
1. **核心矛盾 1**：...
2. **核心矛盾 2**：...

---

## 2. 线上事故复盘与演进历史（Production Postmortems & History）
<!-- 记录该模块曾踩过的坑、代码注释中防范的问题，或重构的演进历程 -->
- **事故与演进背景**：...
- **当前防范机制确立**：...

---

## 3. 被否决的诱人方案（Rejected Alternatives / 切斯特顿之栅）
<!-- 核心防御段落：必须列出 1~2 个看似简单但实际存在严重缺陷的方案，防止后人好心办坏事 -->
- **被否决方案 1：[直觉做法]**
  - *诱人之处*：...
  - *为什么彻底否决*：...

---

## 4. 核心流程与状态机（Business Workflow & State Transitions）
<!-- 必须提供 ASCII 状态机或流转图，标明合法路径与非法拦截路径 -->

[ 状态 A ] ──(合法操作)──► [ 状态 B ] ──(完成)──► [ 终态 ] │ └──(非法操作)──► [ 守卫前置拦截 / 抛出异常 ]

---

## 5. 核心业务规则与计算模型（Business Rules & Calculations）
<!-- 包含具体规则、计算公式、边界条件、并发控制或数据校验策略 -->
- **计算/校验规则**：...
- **精度与并发防护**：...

---

## 6. 技术实现与代码落地点（Supporting Technical Architecture）
<!-- 必须填写真实存在的工程代码相对路径，禁止虚构 -->
- **控制层/页面视图**：`<填入真实路径>`
- **核心业务层**：`<填入真实路径>`
- **模型/持久层**：`<填入真实路径>`
- **数据表/迁移脚本**：`<填入真实表名或脚本路径>`

阶段五：编译全景大地图索引（Phase 5: Compile README.md Index）

在生成上述 Note 后，你必须在 .agents/notes/README.md 中编写全局大地图索引，供日后毫秒级定位检索：

# Agent Notes 规范与大地图索引 — <工程名称>

本文档为当前工程的架构决策与业务知识全景大地图。处理任何任务前必须先在此检索定位。

## 目录拓扑

```text
.agents/notes/
├── architecture/         # 技术架构支线（系统级核心技术决策）
├── <biz-module-1>/       # 业务领域主线（业务模块 1 说明）
└── <biz-module-2>/       # 业务领域主线（业务模块 2 说明）

篇目清单（精确检索源）

技术架构支线 (`architecture/`)

<文件名>.md: [核心解决的问题 + 核心实现机制 + 防御的故障类型]

业务领域主线 (`<biz-module-1>/`)

<文件名>.md: [业务功能场景 + 核心状态机/规则 + 关键防御机制] ```

阶段六：全量落地自检核验（Phase 6: Self-Verification Checklist）

在完成上述文件写入后，你必须调用工具进行自查验证，确保 100% 满足以下 6 项硬指标：

Check 1 (CLAUDE.md)：已存在于根目录，行数在 30~50 行之间，明确指引 AGENTS.md 为唯一真理单源；
Check 2 (AGENTS.md)：已存在于根目录，8 大板块完整填充当前项目的真实信息，无任何空模板占位符；
Check 3 (物理目录)：.agents/notes/ 及其子目录已正确建立在文件系统中；
Check 4 (基线 ADR)：已生成至少 1 篇 architecture/ ADR 和 1 篇业务 ADR，六大段落齐全；
Check 5 (落地点核对)：检查每篇 Note 第 6 节中列出的代码文件路径，确保在当前仓库中真实存在；
Check 6 (大地图对齐)：.agents/notes/README.md 中已准确登记所有已生成的 Note 及其摘要。

阶段七：日常开发维护运转算法（Phase 7: Ongoing Runtime Contract）

完成自举初始化后，你在当前仓库的后续一切开发工作中，必须将本协议内化为运行时行为准则：

处理任何新需求时（三跳协议）：
- 严禁全量载入知识库；
- 提取任务关键词，检索 .agents/notes/README.md 命中 1 篇相关 Note；
- 仅加载该 Note，重点吸收【切斯特顿之栅】和【历史事故】，按其约束编写代码。
代码修改完毕准备提交时（强同步判定）：
- 若改动了数据表（DDL）、状态机、业务计算公式、接口入参或核心 Service，必须在同一提交中修改对应 Note；
- 若重命名了文件或类名，必须同步修正对应 Note 第 6 节的代码落地点；
- 新建 Note 时，必须同步刷新 .agents/notes/README.md 大地图。
执行代码审查时（门禁阻断）：
- 凡核心逻辑变更但未同步修改 Note 的，直接阻断合入（Request Changes）；
- 凡改动踩入 Note 第 3 节被否决诱人方案的，直接驳回并出具严重警告。

阶段八：向用户交付自举报告（Phase 8: Completion Report Format）

当 Phase 1 至 Phase 6 全部执行完毕且自检通过后，你必须向用户输出以下格式的结构化完工汇报：

🎉 Agent Notes 知识库机制与工程宪法已全自动初始化完成！

📁 落地文件资产清单：
├── CLAUDE.md                       [客户端极简引导入口, 已实装]
├── AGENTS.md                       [工程全栈宪法, 8大核心板块已就绪]
└── .agents/notes/
    ├── README.md                   [知识库全景大地图已编译]
    ├── architecture/
    │   └── <生成的技术Note文件名>   [系统技术基线 ADR]
    └── <业务子目录>/
        └── <生成的业务Note文件名>   [业务领域状态机 ADR]

🔍 探测到的工程基线：
- 核心技术栈：<语言及框架>
- 极速验证指令：<提取到的构建/Lint命令>
- 提取的核心业务域：<业务关键词>

✅ 自检核对全部通过，已挂载三跳按需读取协议与代码强同步门禁。后续开发中我将严格遵循本契约执行！