@namewta/speculo 0.1.9 → 0.1.11

package/template/skills/agents-md-builder/references/role-classification.md

@@ -0,0 +1,153 @@
+# Role Classification
+
+## 原则
+
+为每个 manifest 目录判定**唯一**角色。按优先级顺序匹配，命中即停止。
+
+角色决定：
+- 使用哪个模板骨架
+- 证据收集的重点方向
+- AGENTS.md 的章节侧重
+
+## 6 种角色
+
+### 优先级 1：`repo-root`
+
+**判定条件**：目录是项目根目录（扫描起点）。
+
+**识别特征**：
+- 路径等于 `scan_root`
+- 通常包含 `.git`、顶层 CI 配置、workspace 声明等
+
+**模板**：`templates/repo-root-AGENTS.md`
+
+### 优先级 2：`scripts-docs`
+
+**判定条件**：目录是特批的脚本/文档目录。
+
+**识别特征**（满足任一）：
+- 用户显式声明为 scripts-docs
+- 自动检测：目录名匹配 `script`、`scripts`、`docs`、`docker`、`deploy`，且父目录是 manifest 目录
+
+**特殊规则**：
+- 不要求有 manifest 文件
+- 只为根目录生成 AGENTS.md，不为子目录继续生成
+- 必须显式说明“这是特批文档例外，不是 manifest 模块”
+- 必须区分“可执行脚本”“SQL 资产”“配置模板”“运行时数据目录”
+
+**模板**：`templates/scripts-docs-AGENTS.md`
+
+### 优先级 3：`aggregator`
+
+**判定条件**：manifest 声明了子模块、子项目或 workspace 成员。
+
+**各生态识别方式**：
+
+| 生态 | 识别方式 |
+|------|---------|
+| Node.js / TypeScript | `package.json` 含 `workspaces` 字段 |
+| Java / Maven | `pom.xml` 含 `<modules>` 子元素 |
+| Java / Gradle | `settings.gradle` 含 `include` 且当前目录是声明目录 |
+| Rust | `Cargo.toml` 含 `[workspace]` 且当前是 workspace root |
+| Go | 有 `go.work` 且使用 `use` 声明多个模块目录 |
+| Python | `pyproject.toml` 含 `[tool.hatch.workspace]` 或 `[tool.uv.workspace]` |
+| C / CMake | `CMakeLists.txt` 含 `add_subdirectory()` |
+| Dart / Flutter | `pubspec.yaml` 含 `workspace` 且声明了多个 package |
+| .NET | 目录含多个 `*.csproj` 且被父级 `*.sln` 或 Directory.Build.props 统管 |
+
+**关键要求**：
+- 必须解释子模块的分组逻辑，不是只列模块名
+- 必须写清“哪些问题必须进入哪个子模块继续调查”
+- 聚合层只说编排，不展开子模块实现
+
+**模板**：`templates/aggregator-AGENTS.md`
+
+### 优先级 4：`runnable-app`
+
+**判定条件**：无子模块声明，但有明确的运行入口。
+
+**各生态识别方式**：
+
+| 生态 | 识别方式 |
+|------|---------|
+| Node.js / TypeScript | `package.json` 的 `bin` 字段、`main` 指向可执行入口、或存在 `src/main.ts`、`src/index.ts` 且脚本含 `start`/`dev` |
+| Java | 存在 `@SpringBootApplication`、`@QuarkusMain`、`SpringApplication.run()`、`public static void main` |
+| Rust | `Cargo.toml` 含 `[[bin]]` target，或 `src/main.rs` 存在 |
+| Go | `package main` + `func main()` |
+| Python | 含 `__main__.py`、`console_scripts` entry point、或 `if __name__ == "__main__"` |
+| C / CMake | `CMakeLists.txt` 含 `add_executable()` |
+| Ruby | `Gemfile` 含执行入口声明、或 `bin/` 目录含可执行脚本 |
+| Elixir | `mix.exs` 含 `application` 配置且 `mod` 指向 Application 模块 |
+| Dart | `pubspec.yaml` 含 `executables` 字段 |
+
+**关键要求**：
+- 必须写清启动入口、运行时装配、核心应用链路
+- 必须写清内部依赖模块如何接入到当前应用
+- 不改写成叶子模块的膨胀版
+
+**模板**：`templates/runnable-app-AGENTS.md`
+
+### 优先级 5：`contract-module`
+
+**判定条件**：无子模块、无运行入口，主要职责是暴露类型、契约、配置或依赖约束。
+
+**各生态识别方式**：
+
+| 生态 | 识别方式 |
+|------|---------|
+| Node.js / TypeScript | `package.json` 的 `name` 含 `types`/`config`/`tsconfig`，或 `main`/`exports` 仅暴露 `.d.ts` 文件 |
+| Java / Maven | `pom.xml` 的 `artifactId` 含 `bom`、或 `packaging` 为 `pom`（不含 `<modules>`）、或仅含依赖管理 |
+| Java / Gradle | `build.gradle` 使用 `java-platform` 插件 |
+| Rust | `Cargo.toml` 不含 `[[bin]]`，`[lib]` 仅暴露类型宏，且无实质运行时逻辑 |
+| Go | `go.mod` 声明包但目录内仅含类型定义、常量、接口声明，无 `func main` |
+| Python | `pyproject.toml` 仅含类型桩 (`*.pyi`)、或仅暴露 `__init__.py` 无函数体 |
+| 通用 | 目录没有 `src/` 或仅有类型定义文件 |
+
+**关键要求**：
+- 必须解释约束了什么、被谁消费
+- 没有 `src/` 时，显式说明这是约束层而非实现层
+- 不要误写成运行时代码模块
+
+**模板**：`templates/contract-module-AGENTS.md`
+
+### 优先级 6：`capability-module`
+
+**判定条件**：以上都不匹配的其余所有 manifest 目录。
+
+**典型匹配**：
+- 能力库、工具库、业务模块
+- 数据层模块、领域模块
+- 集成模块、中间件模块
+- 共享组件库
+
+**关键要求**：
+- 必须写清导出面、核心分层、关键业务/能力入口
+- 必须写清内部依赖与上游消费方
+- 区分它是更偏能力模块、业务模块还是集成模块
+
+**模板**：`templates/capability-module-AGENTS.md`
+
+## 角色判定流程图
+
+```
+目录有 manifest 文件？
+├── 否 → 是项目根？→ 否 → 是 scripts-docs？→ 否 → 非 manifest 目录，跳过
+│                          └── 是 → repo-root
+│                └── 是 → repo-root
+└── 是 → 是 scripts-docs 目录？→ 是 → scripts-docs
+         └── 否 → 声明了子模块？→ 是 → aggregator
+                  └── 否 → 有运行入口？→ 是 → runnable-app
+                           └── 否 → 仅暴露契约/约束？→ 是 → contract-module
+                                    └── 否 → capability-module
+```
+
+## 角色与模板映射
+
+| 角色 | 模板文件 |
+|------|---------|
+| `repo-root` | `templates/repo-root-AGENTS.md` |
+| `scripts-docs` | `templates/scripts-docs-AGENTS.md` |
+| `aggregator` | `templates/aggregator-AGENTS.md` |
+| `runnable-app` | `templates/runnable-app-AGENTS.md` |
+| `contract-module` | `templates/contract-module-AGENTS.md` |
+| `capability-module` | `templates/capability-module-AGENTS.md` |

package/template/skills/agents-md-builder/references/templates/aggregator-AGENTS.md

@@ -0,0 +1,69 @@
+# <module-name>
+
+## Scope
+
+- 说明当前聚合 manifest 覆盖的目录范围。
+- 明确哪些子模块拥有自己的 AGENTS.md。
+
+## Module Positioning
+
+- 标记当前角色为 `aggregator`。
+- 说明它在父层中的职责（公共能力聚合、业务域聚合、独立服务聚合等）。
+
+## Directory Structure
+
+- 列出直接子目录、关键文件、子级 manifest 模块。
+- 对子级模块按职责分组，而不是纯罗列。
+
+## Responsibilities
+
+- 说明当前聚合层负责模块编排、边界划分和阅读入口。
+- 明确不负责子模块内部实现细节。
+
+## Core Logic
+
+- 解释当前聚合为什么存在。
+- 解释 manifest 的子模块声明在编排什么。
+- 解释子模块之间的关系与进入时机。
+
+## Key Entry Points
+
+- 当前 manifest 文件
+- 代表性子模块的 manifest、启动入口或核心能力入口
+- 必要时补充关键配置或装配入口
+
+## Usage And Change Notes
+
+- 先按当前聚合层的分组逻辑定位子模块，再继续下钻，不要把聚合层写成叶子模块说明。
+- 调整子模块清单、模块归类或聚合职责时，同步检查父层导读。
+- 如果问题已经落到接口、领域逻辑或运行时配置，立即进入对应子模块 AGENTS.md 与源码。
+
+## Dependencies And Collaboration
+
+- 说明当前聚合与父层、子层的协作关系。
+- 说明哪些问题必须下钻到哪个子模块源码。
+
+## Investigation Rule
+
+- 明确：先读本层分组和编排关系。
+- 如果需要具体实现、接口、配置或异常处理，继续进入对应子模块 AGENTS.md 与源码。
+- 文档与代码冲突时以代码事实为准。
+
+## Core Commands
+
+- 面向当前聚合层的构建、测试命令。
+
+## Verification
+
+- 当前聚合层最小可执行校验。
+
+## Routing
+
+- 上级 manifest
+- 子级 manifest（每个附带一句话定位）
+
+## References
+
+- 当前 manifest
+- 关键聚合配置
+- 代表性子模块入口

package/template/skills/agents-md-builder/references/templates/capability-module-AGENTS.md

@@ -0,0 +1,68 @@
+# <module-name>
+
+## Scope
+
+- 说明当前能力型或业务型 manifest 覆盖的目录范围。
+
+## Module Positioning
+
+- 标记当前角色为 `capability-module`。
+- 说明它在整仓中承担的能力或业务职责（能力库、业务模块、集成模块等）。
+
+## Directory Structure
+
+- 列出直接子目录、关键文件、主源码路径、核心分层、资源目录和测试目录。
+- 只保留定位问题需要的结构。
+
+## Responsibilities
+
+- 说明当前模块负责的实现范围、契约范围和边界。
+- 明确不负责的兄弟模块与上层装配职责。
+
+## Core Logic
+
+- 解释当前模块的主干实现路径。
+- 解释最关键的分层、能力点、处理链路或数据流。
+- 解释它更偏能力模块、业务模块还是集成模块。
+
+## Key Entry Points
+
+- 导出入口文件或主包路径
+- 关键源码目录与核心文件
+- 核心资源配置与测试入口
+
+## Usage And Change Notes
+
+- 新增接口、实体、任务或集成能力时，先确认主包路径下的核心分层归属，不要跨层堆逻辑。
+- 改核心逻辑、资源配置或内部依赖时，同步检查上游消费方和对应测试入口。
+- 如果当前模块被运行型应用装配，涉及对外行为变化时要回看装配层。
+
+## Dependencies And Collaboration
+
+- 列出直接内部依赖与直接消费方。
+- 说明当前模块如何被上层应用或兄弟模块使用。
+
+## Investigation Rule
+
+- 明确：先读 manifest，再读主源码路径下最关键的分层，再读资源配置与测试。
+- 如果本文件无法支撑排查，继续顺着依赖模块和消费方代码下钻。
+- 文档与代码冲突时以代码事实为准。
+
+## Core Commands
+
+- 当前模块的测试与构建命令。
+
+## Verification
+
+- 当前模块最小可执行校验。
+
+## Routing
+
+- 上级 manifest
+
+## References
+
+- manifest 文件
+- 主源码路径
+- 关键源码目录
+- 关键资源与测试入口

package/template/skills/agents-md-builder/references/templates/contract-module-AGENTS.md

@@ -0,0 +1,65 @@
+# <module-name>
+
+## Scope
+
+- 说明当前契约/约束型 manifest 覆盖的目录范围。
+
+## Module Positioning
+
+- 标记当前角色为 `contract-module`。
+- 说明它负责依赖约束、版本对齐、类型契约、配置契约或导出契约。
+
+## Directory Structure
+
+- 列出直接子目录与关键文件。
+- 如果没有 `src/` 或主源码目录，要显式说明这是约束层而不是实现层。
+
+## Responsibilities
+
+- 说明当前模块约束了什么、暴露了什么。
+- 明确不负责运行时代码或业务处理。
+
+## Core Logic
+
+- 解释当前 manifest 如何提供依赖对齐、导入关系或契约出口。
+- 解释它由谁引用、为什么需要独立出来。
+
+## Key Entry Points
+
+- manifest 文件
+- 若存在类型定义、配置文件或导出文件，列出这些文件
+
+## Usage And Change Notes
+
+- 改版本约束、依赖管理或契约导出前，先确认直接消费它的模块。
+- 如果目录没有实现代码，要明确它仍然是约束层；不要补写成运行时代码模块。
+- 当改动会影响构建对齐或依赖传递时，同步检查根级或聚合层导读。
+
+## Dependencies And Collaboration
+
+- 说明父模块、子模块或消费方如何使用它。
+- 说明它不直接承载业务实现。
+
+## Investigation Rule
+
+- 明确：先读 manifest 的依赖管理、导入关系和导出方式。
+- 若要判断实际实现效果，继续进入引用它的消费模块源码。
+- 文档与代码冲突时以代码事实为准。
+
+## Core Commands
+
+- 当前模块的最小构建校验命令。
+
+## Verification
+
+- 当前模块最小可执行校验。
+
+## Routing
+
+- 上级 manifest
+
+## References
+
+- manifest 文件
+- 关键导出或配置文件
+- 主要消费方

package/template/skills/agents-md-builder/references/templates/repo-root-AGENTS.md

@@ -0,0 +1,71 @@
+# <project-name>
+
+## Scope
+
+- 说明当前根级 manifest 覆盖的目录范围。
+- 明确哪些更深层 manifest 目录会接管说明。
+
+## Module Positioning
+
+- 标记当前角色为 `repo-root`。
+- 说明根目录在整个项目中承担的总入口职责。
+- 概括顶层模块如何分层（如有 workspace / multi-module）。
+
+## Directory Structure
+
+- 列出顶层直接子目录与关键根级文件。
+- 点明哪些中间层目录本身没有独立 AGENTS.md，事实如何上收。
+
+## Responsibilities
+
+- 说明根级目录负责哪些项目边界、装配边界和阅读路径。
+- 明确不负责的子模块内部实现细节。
+
+## Core Logic
+
+- 解释顶层 manifest 如何组织子模块或 workspace。
+- 解释从根级进入项目时，应该如何定位到聚合层或叶子层。
+- 不要只列模块名，要解释分层理由。
+
+## Key Entry Points
+
+- 顶层 manifest 文件
+- workspace / multi-module 配置
+- 顶层直接子模块的代表性入口
+- 关键根级配置文件
+
+## Usage And Change Notes
+
+- 先用顶层 manifest 与模块分组判断问题落在哪个聚合层或叶子层，不要在根层直接推断子模块细节。
+- 调整顶层模块清单、父依赖或构建插件时，先检查根级配置与子模块导读是否需要同步。
+- 根层只负责边界与导航；涉及具体实现时，必须进入对应子模块继续调查。
+
+## Dependencies And Collaboration
+
+- 说明顶层模块之间的协作关系。
+- 说明哪些问题必须下钻到子模块源码。
+
+## Investigation Rule
+
+- 明确：先用本文件建立范围与导航。
+- 如果本文件无法回答问题，继续深入子模块 AGENTS.md、manifest、关键源码、配置与测试。
+- 文档与代码冲突时以代码事实为准。
+
+## Core Commands
+
+- 根级常用构建、测试、运行命令。
+
+## Verification
+
+- 根级最小可执行校验。
+
+## Routing
+
+- 链接全部子级 manifest 目录（每个附带一句话定位）。
+
+## References
+
+- 顶层 manifest
+- workspace / multi-module 配置
+- 关键根级配置文件
+- 代表性入口文件

package/template/skills/agents-md-builder/references/templates/runnable-app-AGENTS.md

@@ -0,0 +1,69 @@
+# <module-name>
+
+## Scope
+
+- 说明当前运行型 manifest 覆盖的目录范围。
+
+## Module Positioning
+
+- 标记当前角色为 `runnable-app`。
+- 说明它是运行时装配入口、Web 服务入口、CLI 工具入口或独立应用入口。
+
+## Directory Structure
+
+- 列出直接子目录、关键文件、主源码路径、资源目录和测试目录。
+- 指出最重要的实现分层与配置位置。
+
+## Responsibilities
+
+- 说明当前模块负责的启动、装配、应用入口和运行边界。
+- 明确不负责哪些内部依赖模块的实现细节。
+
+## Core Logic
+
+- 解释启动入口如何组织应用。
+- 解释核心链路（路由/控制器/服务/数据层 或 等价链路）如何协作。
+- 解释内部依赖模块如何接入当前应用。
+
+## Key Entry Points
+
+- 启动入口文件
+- 关键路由/控制器/服务入口
+- 核心配置文件
+- 测试入口
+
+## Usage And Change Notes
+
+- 改启动链路、装配逻辑或运行参数时，先检查启动入口、运行时配置与直接内部依赖模块。
+- 新增或调整应用入口时，优先确认归档位置、配置联动和对应下游模块是否同步。
+- 当前层是运行时装配入口，不要在这里替代内部模块的业务导读。
+
+## Dependencies And Collaboration
+
+- 列出直接内部依赖模块。
+- 说明当前模块作为运行时装配层，如何把这些模块组装起来。
+
+## Investigation Rule
+
+- 明确：先读 manifest，再读启动入口与配置，再顺着核心链路下钻。
+- 如果问题落到业务模块内部，必须跳到对应模块 AGENTS.md 与源码继续调查。
+- 文档与代码冲突时以代码事实为准。
+
+## Core Commands
+
+- 当前模块的开发、构建、测试、运行命令。
+
+## Verification
+
+- 当前模块最小可执行校验。
+
+## Routing
+
+- 上级 manifest
+
+## References
+
+- manifest 文件
+- 启动入口
+- 关键源码目录
+- 关键资源与测试入口

package/template/skills/agents-md-builder/references/templates/scripts-docs-AGENTS.md

@@ -0,0 +1,51 @@
+# <dir-name>
+
+## Scope
+
+- 说明当前文件只覆盖此脚本/文档根目录。
+- 明确子目录不再下钻生成子级 AGENTS.md。
+
+## Module Positioning
+
+- 标记当前角色为 `scripts-docs`。
+- 说明这是项目脚本资产或文档的总索引，不是标准的 manifest 模块。
+
+## Directory Structure
+
+- 列出一级子目录与关键根级文件。
+- 区分可执行脚本、配置模板、SQL/迁移、任务清单、样例数据与运行时数据目录。
+
+## Responsibilities
+
+- 说明当前目录负责哪些资产索引、阅读路径与维护约束。
+- 明确不负责子目录独立文档拆分。
+
+## Core Assets
+
+- 概括各类子树的用途（可按 3-5 类分组）。
+- 说明关键入口文件与常见使用场景。
+
+## Key Entry Points
+
+- 指出优先查看的脚本、配置、入口文件与样例。
+
+## Usage And Change Notes
+
+- 先区分“可直接执行的管理脚本”“数据资产”“配置模板”“运行时数据目录”，不要把它们混写成同一类入口。
+- 修改此目录内容时，只维护根级 AGENTS.md，不要为子目录继续生成文档节点。
+- 涉及运行时数据目录（如 `data/`、`log/`、`store/`）时，只写用途说明，不把运行时数据目录当成文档模块。
+
+## Investigation Rule
+
+- 先用当前索引定位子树与入口。
+- 如果当前文件不足以回答问题，继续深入对应脚本、配置或数据文件。
+- 文档与文件内容冲突时，以实际脚本和配置为准。
+
+## Maintenance
+
+- 变更时先更新当前 AGENTS.md。
+- 只维护根目录这一层，不为子目录生成子级文档。
+
+## References
+
+- 此目录下的关键脚本、配置与入口文件

package/template/skills/agents-md-builder/references/writing-style.md

@@ -0,0 +1,145 @@
+# Writing Style
+
+默认使用中文，目标是**平衡型模块导读**：比索引更深，但不写成长篇百科。
+
+## 中文排版
+
+遵循以下排版规则，避免机翻味和目录卡片化。
+
+### 空格
+
+- 中文与英文之间加空格：
+  - `使用 Git 管理版本`
+  - `接入 Spring Boot`
+- 中文与数字之间加空格：
+  - `新增 3 个入口`
+  - `默认保留 2 条阅读路径`
+- 链接前后保留正常中文空格，不要把链接和汉字黏在一起。
+
+### 标点
+
+- 中文语境使用全角标点：
+  - `注意：这里只写导航，不复制实现细节。`
+- 英文代码、命令、路径保留半角形式：
+  - `先读 package.json，再读 src/main.ts。`
+
+### 术语
+
+- 保留业界通用英文术语：`Controller`、`Service`、`Router`、`Store`、`API`、`SDK`、`CLI`
+- 有稳定中文表达的通用概念直接写中文：`数据库`、`服务器`、`配置约束`、`工作区`
+- 首次出现的重要术语可写中英对照，但不要每次重复翻译
+- 不要把常用框架术语硬翻成别扭中文
+
+### 句式
+
+- 优先短句，一句话只说一层意思
+- 少用被动句：
+  - 差：`该文件被用来描述模块。`
+  - 好：`该文件用于描述模块。`
+- 少写空话：
+  - 差：`如需更多信息请查看源码。`
+  - 好：`若要确认运行入口，先读 src/main.ts，再读 router 与 request 链路。`
+- 不要把不确定推断写成既定事实
+
+### 结构
+
+- 先写模块位置，再写它如何工作，再写如何继续下钻
+- 使用列表承载职责、入口、边界和排查顺序，不堆长段落
+- `Usage And Change Notes` 要写成可执行提醒，不要写成泛泛的“修改时注意兼容性”
+
+## 长度与密度
+
+| 角色 | 推荐行数 |
+|------|---------|
+| `repo-root` | 45-75 行 |
+| `scripts-docs` | 40-65 行 |
+| `aggregator` | 40-70 行 |
+| `runnable-app` | 50-85 行 |
+| `capability-module` | 45-80 行 |
+| `contract-module` | 35-60 行 |
+
+每个章节尽量 2-5 个高信息量要点。
+
+## 好写法 vs 差写法
+
+### Scope / Module Positioning
+
+- ✅ 先说明模块在项目中的位置，再说明它如何工作
+- ✅ 用“入口文件 + 协作目录 + 消费关系”描述排查路径
+- ✅ 写清“看完本文件之后，下一步去哪里”
+
+- ❌ “主实现通常位于 `src/`”
+- ❌ “当前包暴露共享能力”
+- ❌ “如需更多信息请查看源码”
+
+### Key Entry Points
+
+- ✅ 直接点名类、配置、测试与关键目录，例如：
+  - `Application.java` — 启动类
+  - `web/controller` — REST 控制器目录
+  - `application-dev.yml` — 开发环境配置
+  - `src/main.ts` — 应用入口
+  - `src/router/index.ts` — 路由注册
+
+- ❌ “主实现位于 `src/`”
+- ❌ “api/ — 接口层”
+- ❌ 只列目录，不解释这些目录为什么重要
+
+### Usage And Change Notes
+
+- ✅ 写成可执行提醒：
+  - “新增接口时先确认 controller 所属归档单元，再同步检查 bo/vo 和前端接口契约。”
+  - “改请求层时先检查 `packages/core`、环境变量和下载链路。”
+  - “改导出面、公共类型或运行时工具时，先列出直接消费它的模块，避免隐式破坏调用方。”
+
+- ❌ “修改时注意兼容性”
+- ❌ “按需查看相关代码”
+- ❌ “先看 controller、service、domain”
+
+### Investigation Rule
+
+- ✅ 必须写成可执行顺序：
+  ```
+  1. 先读 pom.xml 了解依赖和模块声明。
+  2. 再读启动类或核心入口包。
+  3. 再读资源配置与测试。
+  4. 仍不够时顺着内部依赖继续下钻。
+  5. 文档与代码冲突时以代码事实为准。
+  ```
+
+- ✅ 必须明确：
+  - 本文件是入口，不是终点
+  - 文档与代码冲突时以代码事实为准
+
+- ❌ “需要时查看源码”
+- ❌ “如需更多信息请参考代码”
+
+## 语气要求
+
+- 直接、事实化、可执行
+- 不写宣传性语言（“业界领先的”“强大的”“优雅的”）
+- 不把不确定推断写成既定事实
+- 不用感叹号
+- 不用“请”“建议”等婉转表达——直接说“先读 X，再读 Y”
+
+## 删除测试
+
+写完每个 AGENTS.md 后，逐行执行删除测试：
+
+> **“删除这一行会导致 AI 代理犯错吗？”**
+
+- 如果不会 → 删除这一行
+- 如果会 → 保留
+
+这个测试是 AGENTS.md 质量的核心防线。它强制每一个字都对 AI 代理有操作价值。
+
+### 删除测试示例
+
+| 行 | 删掉会犯错吗？ | 判定 |
+|----|-------------|------|
+| “该模块负责用户认证与授权” | 会 → AGENTS 可能在错误模块找认证逻辑 | ✅ 保留 |
+| “推荐使用 VS Code 进行开发” | 不会 → AGENTS 不需要知道用什么编辑器 | ❌ 删除 |
+| “模块使用 TypeScript 编写” | 不会 → AGENTS 打开文件就能看出 | ❌ 删除 |
+| “先读 `src/main.ts`，再读 `src/router/index.ts`” | 会 → AGENTS 不知道该从哪开始 | ✅ 保留 |
+| “注意代码质量” | 不会 → 这是无操作价值的空话 | ❌ 删除 |
+| “改 `src/api/` 时同步检查前端接口契约” | 会 → 这是跨边界风险提醒 | ✅ 保留 |