agentleFS
tlzmw001tlzmw001/aitest-kit/.agents/skills/knowledge-build/SKILL.md

knowledge-build

Skill13 starsChanged 3 months agoMITView on GitHub

从开发文档构建或更新测试知识库(L0 架构索引 / L1 模块功能 / L2 需求变更),以灰盒测试人员视角提取可测试契约

The file

Files
SKILL.md

测试知识库构建

从 $doc_dir 目录下的文档构建或更新测试知识库,输出到 $knowledge_dir(未指定时默认为 $doc_dir 同级的 knowledge/ 目录)。

你的角色

你是一个新入职的测试人员。你不能阅读源码实现,只能从文档和接口定义文件中获取信息。

信息来源

主要信息源是 $doc_dir 目录下的文档。

以下文件也可以读取(它们定义了系统的外部行为,属于测试人员应了解的范畴):

  • 接口定义文件:.proto、OpenAPI/Swagger spec 等
  • 配置文件:.json、.yaml、.toml、.ini 等
  • 数据文件:.tsv、.csv 等(了解数据格式和字段含义)
  • Schema 文件:JSON Schema、数据库 DDL 等

禁止读取的是源码实现(.py、.java、.go、.ts 等)——测试人员关注系统做什么,不关注怎么实现。

每条信息必须能溯源到文档或上述可读文件,无法确认的标 [?]。

信息边界(灰盒)

可以包含:API 接口定义、请求/响应结构、proto message/service、配置项含义与默认值、存储 Key 格式、错误码、业务算法公式

不包含:源码函数名、行号、变量名、内部实现逻辑

执行流程

第一步:盘点文档

读取 $doc_dir 下所有文档,将每份文档分类为:

  • 系统总览:整体架构、API 列表、流程
  • 迭代变更:增量改动需求
  • 接入指南:组件/SDK 使用方式
  • 历史测试文档:已有测试用例、测试报告
  • 其他:标注类型

第二步:判断模式

检查 $knowledge_dir 目录:

  • 初始化模式(目录不存在或无 L0 文件)→ 执行第三步
  • 增量更新模式(已有 L0 文件)→ 执行第四步

第三步:初始化构建

  1. 分析所有文档,识别系统模块和变更迭代
  2. 创建目录结构:
    $knowledge_dir/
    ├── L0_system_architecture.md
    ├── L1/
    └── L2/
  3. 按模板生成 L0、L1、L2 文件
  4. 文档中没有的信息一律标注 [?],不猜测
  5. 生成完毕后,向用户输出知识库摘要(模块列表 + [?] 统计)

第四步:增量更新

  1. 读取已有的 L0 索引,了解当前知识库结构
  2. 对比新文档与已有 L2,识别:
    • 全新的迭代 → 新建 L2 文件
    • 已有迭代的补充信息 → 更新对应 L2 文件
  3. 根据变更影响,更新受影响的 L1 模块文件
  4. 如果出现新模块 → 新建 L1 文件
  5. L0 一致性校验:用新文档内容逐项校验 L0 现有描述,必须检查:
    • Pipeline 阶段顺序是否与新文档一致(这是最容易过时的部分)
    • 版本号是否需要更新
    • 服务拓扑是否有变化
    • 发现不一致时直接修正 L0,不能跳过
  6. 更新 L0 索引表
  7. 向用户输出变更摘要(新增/修改了哪些文件,新增了哪些 [?])

分层说明

L0 — 系统架构(路由索引)

  • 控制在 80 行以内
  • 一段话描述系统功能
  • 服务拓扑
  • Pipeline 阶段概览
  • 模块索引表:模块名 | 说明 | L1 路径 | 相关 L2 路径
  • 不包含具体业务规则

L0 — 系统架构(路由索引)补充

  • 如果项目有接口定义文件(.proto、OpenAPI spec),在 L0 中添加"接口契约"章节,链接到这些文件
  • 这些文件是输入/输出结构的权威来源,知识库不需要复制字段表,链接即可

L1 — 模块功能(可测试契约)

  • 每个文件控制在 150 行以内
  • 功能差异大的模块拆成独立文件
  • 反映当前最新全貌(增量更新时合并变更到已有文件)
  • 输入/输出章节:如果系统有 proto 或 OpenAPI 定义,在章节中链接到对应的 message/schema 定义,不重复列字段
  • 接口契约必须记录:每个 L1 模块如果有对应的 HTTP/gRPC 测试入口,必须在"输入"章节之前添加"接口"章节,包含:(1) 完整端点路径(如 POST /api/v1/recommend),从 proto/OpenAPI/路由定义文件中提取;(2) 链接到请求/响应 Schema 定义文件。即使模块只关注部分字段,L1 也必须至少列出请求体中所有必填字段及其类型(或链接到完整定义),因为 test-design 需要构造完整请求体才能生成可执行用例

L2 — 需求变更

  • 每个文件控制在 100 行以内
  • 描述变更 delta 和测试重点

L1/L2 模板

L1 模块文档模板见 aitest_config/refs/l1-template.md。 L2 需求变更文档模板见 aitest_config/refs/l2-template.md。

生成 L1/L2 文件时必须读取对应模板,按模板结构输出。

质量约束

  1. 不猜测:文档没写的标 [?],附简短说明缺什么(如 [?错误码未明确]、[?是否必填])
  2. 不脑补必填性:字段是否必填、是否有默认值,文档没明确说的就标 [?]
  3. 溯源原则:每条规则应可追溯到具体文档原文,不做推理延伸
  4. 行数限制:L0 ≤ 80 行,L1 ≤ 150 行,L2 ≤ 100 行
  5. 增量更新时:只修改受新文档影响的文件,不动其他文件

[?] 标注规范

标注 [?] 时按类型分类,便于后续分批补全:

  • [?行为未定义: ...] — 文档未说明某条件下的系统行为(如"候选券为空时的行为"),需读代码或找产品确认
  • [?值未明确: ...] — 具体字段名、加密方式、阈值等文档未给出(如"7 个特征字段名"),需读配置或代码提取
  • [?可观测性缺失: ...] — 模块缺少日志/指标/健康检查的描述,需审计实际可观测覆盖度

补全时建议按 pipeline 数据流顺序(校验→路由→粗排→特征→打分→校准→发放)逐模块处理,上下文连贯性更好,更容易发现跨模块问题。

错误场景标注规范

错误场景段落中,区分两类:

  • 设计行为:系统有意为之的降级/兜底(如"候选券为空→返回空列表"),直接描述行为
  • [!风险]:系统未处理的异常路径(如"Redis 连接异常未捕获,会导致整个请求失败"),用 [!风险] 标记,这些是高价值测试点

可观测状态段落要求

每个 L1 模块必须填写"可观测状态"段,包含:

  • 已有的可观测手段(日志级别+内容、Redis Key、API 端点、指标等)
  • 盲区:关键路径上缺少日志/指标的地方(如"目录不存在时无日志"、"限流触发无日志")
  • 已定义但未使用的错误码/常量(如"STOCK_EMPTY=1006 已定义但代码未使用"),这类信息对测试设计有价值

完成后输出

执行完毕后,向用户输出:

## 知识库构建摘要

模式:初始化 / 增量更新
文档源:(读了哪些文档)

### 文件清单
(列出所有生成/修改的文件及行数)

### [?] 统计
(列出所有标了 [?] 的信息点,按模块分组)

### 待确认项
(需要用户补充或确认的关键信息)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.