@niujiajie/freespec 0.0.0-stage → 1.15.0

package/skill-files//344/273/273/345/212/241/references//346/212/244/346/240/217.md

@@ -0,0 +1,43 @@
+# 护栏
+
+护栏挂在动作上，不靠回头翻清单。落盘前运行 `scripts/check-tasks.mjs`，脚本退出码不是 0，就不能交。必须项只在这一份。`references/约束.md` 只是尽量项。
+
+## 写每一条时查
+
+1. 用 `- [ ]` 开头，一行只写一条。勾选只改成 `- [x]`，不换别的符号。说明不要用 `- ` 开头。
+2. 每条写上「完成：」，后面写怎样算做完。脚本查这个标记在不在。功能点对得准不准人看，脚本不查。
+3. 设计里没有的章，不生造任务。设计只写了方法名、没有步骤的，不在这里补算法。
+
+## 重写整份清单时查
+
+1. 已经是 `- [x]` 的条目原样保留，不弄丢。
+2. 设计里没有的章，对应任务组整组删掉，不留空标题。
+3. 仓库里的脚本进仓库、已经在数据库执行过，分成两条写。
+
+## 遇到这些，停手
+
+| 遇到什么 | 停下后干什么 |
+|---|---|
+| 功能点或设计缺到写不出这一条 | 停，问人。缺的记成需求待定，不要猜一句结果填上 |
+| 设计步骤前后矛盾 | 停，问人，指出矛盾在哪两处。不要在任务里自己挑一边 |
+
+## 落盘前查
+
+1. 跑 `node scripts/check-tasks.mjs <任务清单.md>`，退出码是 0。
+2. 对话只报路径和没把握的条目。不开始写代码，不说「接下来实现」。
+
+## 脚本核对
+
+上面的句子给人读。脚本只执行下面这块。要放宽、改禁词，改这里，不用改脚本。
+
+```json
+{
+  "核对": {
+    "任务行格式说明": "第{行}行的任务没有用 - [ ] 或 - [x] 开头",
+    "空组说明": "「{标题}」这个组下面一条任务都没有，整组删掉或补上任务",
+    "任务行禁词": ["优化", "完善", "提升", "大概", "可能", "后续再看"],
+    "禁词说明": "第{行}行用了「{词}」，写清具体做什么",
+    "完成标记说明": "第{行}行没有「完成：」。写上怎样算做完"
+  }
+}
+```

package/skill-files//344/273/273/345/212/241/references//347/262/222/345/272/246.md

@@ -0,0 +1,23 @@
+# 任务粒度
+
+每条用简体中文写清做什么，并写上设计第几章、对应哪条功能点、怎样算做完。不要只写内部代号。
+
+禁止：优化、完善、提升、大概、可能、后续再看，以及「实现某模块」「完成后端」「做增删改查」。
+
+合适的一条：一个接口加上它的服务和主要失败分支，或一张表，或一页关键交互。
+
+不要每个导入、每个取值方法、每个按钮单独一条，除非设计把那一项单独要求出来。
+
+同一服务里紧耦合的接口可以并成一条，但句子里要列全接口和分支。
+
+缓存、开关、线程池、定时任务可以和相邻任务写在一起，句子里必须点出这些词。禁止只写「实现配置」却不出现「线程池」或「开关」。
+
+仓库里的脚本，和已经在数据库执行过，分成两条。
+
+设计只写了方法名、没有步骤的，不要在任务里补算法。
+
+没有对应设计章节的组整组删掉。没有设计时，合成一组「要做的事」，仍然用 `- [ ]`。
+
+重写清单时保留已经是 `- [x]` 的条目，不要重排后弄丢。
+
+一条里的设计引用不要超过三处。

package/skill-files//344/273/273/345/212/241/references//347/272/246/346/235/237.md

@@ -0,0 +1,8 @@
+# 约束
+
+这里只写尽量做到的事。必须项在 `references/护栏.md`。
+
+## 尽量
+
+- 一条对应一个接口加它的服务，或一张表，或一页。
+- 缓存、开关、定时任务、线程池在句子里点出来。

package/skill-files//344/273/273/345/212/241/scripts/check-tasks.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * 任务清单核对。条文在 references/护栏.md 的 json 块里，脚本只执行。
+ * 护栏未通过则退出码 1。
+ * 用法：node check-tasks.mjs <任务清单.md>
+ *
+ * 查四样：任务行格式（- [ ] 或 - [x] 开头）、空组（组标题下没有任务）、
+ * 任务行禁词、伪任务行（看着像列表项但不是勾选格式）。
+ * 一级标题（文档总标题）不算组。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const docPath = process.argv[2];
+if (!docPath) {
+  console.error('用法：node check-tasks.mjs <任务清单.md>');
+  process.exit(2);
+}
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const rulePath = path.join(here, '..', 'references', '护栏.md');
+const fence = fs.readFileSync(rulePath, 'utf8').match(/```json\s*([\s\S]*?)```/);
+let rules = {};
+if (fence) {
+  try {
+    rules = JSON.parse(fence[1]).核对 ?? {};
+  } catch (error) {
+    console.error(`护栏.md 里的 json 读不了：${error.message}`);
+    process.exit(2);
+  }
+}
+
+function fill(template, vars) {
+  return String(template ?? '未通过').replace(/\{([^}]+)\}/g, (_, key) => vars[key] ?? '');
+}
+
+const lines = fs.readFileSync(docPath, 'utf8').split(/\r?\n/);
+const found = [];
+const groups = [];
+let group = null;
+
+lines.forEach((line, index) => {
+  const number = index + 1;
+  const head = /^(#{1,6})\s+(.+)$/.exec(line);
+  if (head) {
+    group = { title: head[2].trim(), level: head[1].length, hasTask: false };
+    groups.push(group);
+    return;
+  }
+  if (!/^\s*-\s+/.test(line)) return;
+  if (group == null) {
+    group = { title: '清单开头', level: 0, hasTask: false };
+    groups.push(group);
+  }
+  group.hasTask = true;
+  if (!/^\s*-\s+\[[ xX]\]/.test(line)) {
+    found.push(fill(rules.任务行格式说明, { 行: number }));
+    return;
+  }
+  if (!line.includes('完成：')) {
+    found.push(fill(rules.完成标记说明, { 行: number }));
+  }
+  for (const word of rules.任务行禁词 ?? []) {
+    if (line.includes(word)) {
+      found.push(fill(rules.禁词说明, { 行: number, 词: word }));
+    }
+  }
+});
+
+for (const item of groups) {
+  // 一级标题是文档总标题，不算组；没有任务的组标题是残留。
+  if (item.level >= 2 && !item.hasTask) {
+    found.push(fill(rules.空组说明, { 标题: item.title }));
+  }
+}
+
+if (found.length > 0) {
+  console.error(`未通过 ${found.length} 项：`);
+  for (const item of found) console.error(`- ${item}`);
+  process.exit(1);
+}
+console.log('通过');

package/skill-files//345/206/231Java/references/Java/350/247/204/350/214/203.md

@@ -0,0 +1,25 @@
+# Java 默认写法
+
+本仓库已有的分层、异常、返回体、路径参数、工具库写法优先。没有先例时才用下面这些。
+
+控制器只接参数、做校验和鉴权，然后调服务。业务判断不要写在控制器里。
+
+多表写入要回滚时，在服务实现上加事务。传播行为和只读标记跟仓库里同类方法一致。改代码前确认模块和构建文件路径。
+
+判空和字符串优先 Hutool 的 StrUtil、CollUtil，其次 Commons 或 Spring 自带工具。
+
+简单对象用 Lombok，不要手写 Getter 和 Setter。对象转换优先 Stream。复杂逻辑可以用循环。对外不要返回裸 null，跟项目现有习惯用空集合或 Optional。
+
+日志用项目已有的方式。核心入口、外部调用前后、捕获处要打，带业务编号。不要打没有信息的「成功了」。
+
+不要空捕获。业务异常用项目里已有的类型。没有时再用 BizException 或 ServiceException。不要把数据库异常或空指针栈返回给调用方。
+
+不要把密钥写进代码。新增配置要在设计里有说明，放在项目已有的配置文件。
+
+改已有接口默认只追加。要破坏旧用法，必须是这次明确要求的。写操作按设计考虑能不能重复提交。
+
+名字用业务词。不要用 data1、obj2。布尔字段不要以 is 开头。简单增删改查直接写在服务里，不要为了模式再包一层。注释只解释看不出来的逻辑。
+
+目标类已经存在就改它，不要平行再建一个同职责的类。至少先读一个同包的同类。
+
+不要用 Executors 给业务建线程池，除非仓库里已经这样写。

package/skill-files//345/206/231Java/references//345/215/261/351/231/251/345/206/231/346/263/225.md

@@ -0,0 +1,27 @@
+# 危险写法
+
+这里只收写了会出事的：静默失效、数据损坏、安全漏洞。风格约定不在这里，在 `references/Java规范.md`。动手前扫一遍，写完自查一遍。
+
+## 数据库
+
+1. UPDATE 和 DELETE 必须有删不掉的 WHERE。动态 `<where>` 加一堆 `<if>`，条件全空时会更新全表。Java 侧先校验条件非空，XML 里 WHERE 写死。
+2. MyBatis 传参数一律 `#{}`。`${}` 是拼字符串，能被注入。动态表名、排序列必须先过白名单再进 `${}`。
+
+## 事务
+
+3. `@Transactional` 只加在 Service 层的 public 实例方法上。类级注解、Controller 上的、static 方法上的、`new` 出来的对象上的，都不生效。
+4. 写库的方法显式写 `rollbackFor = Exception.class`。不写的话，受检异常抛出后事务照样提交，半截数据落库。
+5. 同类里 `this.doCreate()` 不走 Spring 代理，事务不生效。拆到另一个 Bean 调用。
+6. 事务方法里 catch 了异常只打日志不重抛，事务照样提交。要回滚就重抛，或写 `setRollbackOnly()`。
+
+## 性能
+
+7. 循环里不查库。列表页 100 条主记录，循环里逐条查子记录，就是 101 次 SQL。改 JOIN 或批量 IN。
+8. 循环里不单条 insert。500 条数据就是 500 次 SQL。用 `<foreach>` 拼一条批量 insert，或 `saveBatch`。
+9. 循环里不调远程接口（HTTP、Feign、RPC）。改批量接口。没有批量接口时停下来问，不要先写了再说。
+
+## 金额与并发
+
+10. 金额字段一律 `BigDecimal`，禁止 `double`、`float`。比较用 `compareTo`，`equals` 会因精度位数不同判不等。
+11. 单例 Bean 里不放可变实例字段给并发读写。`SimpleDateFormat` 不能共享，用 `DateTimeFormatter`。
+12. `lock()` 后面紧跟 `try-finally` 释放。`countDown()` 放 `finally`。两者漏了，异常时锁不释放、等待永久阻塞。

package/skill-files//345/206/231Java/references//345/256/214/346/210/220/345/257/271/347/205/247.md

@@ -0,0 +1,15 @@
+# 完成对照
+
+每条任务开始前，用几行中文写：依据哪一节、要改哪些文件、怎样算做完。不超过十二行。用户说直接写码时可以不写这几行。
+
+勾选之前仍要写完成对照，不超过五行。即使用户说这轮做几条，也不能攒到最后。
+
+三行就够，每行都能单独看懂：
+
+- 依据：设计第几章，或功能点原句
+- 文件：改了哪些
+- 测试：是否通过。有用例时要先看到失败，再看到通过
+
+不要写「已搞定」「写完了」「按设计实现了」。步骤用完整中文，不要用写边、选桶、查 bind。
+
+类名和路径可以留，旁边说明做了什么。

package/skill-files//345/206/231Java/references//346/212/244/346/240/217.md

@@ -0,0 +1,35 @@
+# 护栏
+
+护栏挂在动作上，不靠回头翻清单。做到哪一步，就查哪一步。必须项只在这一份。`references/约束.md` 只是尽量项。
+
+## 开工前查
+
+1. 有测试用例时，先确认这些测试现在跑不过。没看到失败，不写实现。
+2. 有任务清单时，只做最前面一条没勾的。开工前按 `references/完成对照.md` 写三行。
+3. 做哪条任务，只读设计里对应的那几节，不通读整篇设计。读不着的按停手处理。
+
+## 写码中遇到这些，停手
+
+| 遇到什么 | 停下后干什么 |
+|---|---|
+| 设计里某个方法只有名字、没有步骤 | 停，问人。不要编算法，也不要把算法补进设计或任务清单 |
+| 仓库现状和设计写的对不上 | 停，问人，指出设计哪一句和哪个文件对不上。不改设计正文，也不按错的硬写 |
+| 要改需求、设计、任务、用例的正文才能继续 | 停，问人。设计那一步可以改需求文档里的一个词。写代码这一步不行。用户明确要求才可以改 |
+| 用例怎么跑都不变红 | 停，问人。说明用例可能没断言到行为 |
+
+## 勾选前查
+
+1. 完成对照已经写：依据、文件、测试，三行。
+2. 有测试用例时，这一条对应用例的测试要先失败，再通过。没有测试用例时，按任务写完再勾。
+3. 涉及数据库脚本时，写清是脚本进仓库，还是已经在库里执行过。两件事不写成一句。
+4. 用户说这轮做几条，也是做完一条、对照一条、勾一条。不攒到最后一起勾。
+
+## 宣布做完前查
+
+1. 勾了几条，就是做完了几条。没勾的不说做完了。
+2. 对话报：做到哪一条、测试是否通过。试错过程不写进去。
+
+## 对话里不许
+
+- 不贴代码全文和文档全文。
+- 不说「接下来审代码」「接下来验收」。做完就停，等用户点名。

package/skill-files//345/206/231Java/references//347/272/246/346/235/237.md

@@ -0,0 +1,8 @@
+# 约束
+
+这里只写尽量做到的事。必须项在 `references/护栏.md`。
+
+## 尽量
+
+- 沿用这个仓库里已经有的写法。
+- 两份文档都没有时，按对话里已经说清的内容实现，并写明假设。

package/skill-files//345/206/231Java/references//350/270/251/345/235/221.md

@@ -0,0 +1,17 @@
+# 写 Java 时停下的情况
+
+设计或任务里某个方法只有名字、没有步骤：停下来问。不要自己编算法再勾上。
+
+算法和状态迁移不能建立在假设上。假设可以有，但要少，而且要写明。核心逻辑不能靠没确认的假设。
+
+一次只做一条未勾选任务。即使用户说一次做几条，也做完一条、对照一条、勾一条。不要攒到最后一起勾。
+
+旧数据或旧入口怎么处理，要写明。仓库里的脚本和已经在库里执行过，要分开说。
+
+没有用例、也没有任务清单时，按对话里已经说清的内容实现，并写明假设。
+
+对话里只报做到哪一条、测试是否通过。试错过程不写入完成对照。
+
+写 SQL、事务、循环、金额、线程前，先扫一遍 `references/危险写法.md`。那里是写了会出事的写法，不是风格建议。
+
+做完就停。

package/skill-files//345/256/241Java/references//346/212/244/346/240/217.md

@@ -0,0 +1,19 @@
+# 护栏
+
+护栏挂在动作上，不靠回头翻清单。必须项只在这一份。`references/约束.md` 只是尽量项。
+
+## 开评前查
+
+1. 评审范围明确：这次评什么，用户说了算，不猜。用户在本会话说过的警告不用管，这轮不再报。
+2. 只看 diff 和搜索到的证据。没搜到证据的，不升成必须改。
+
+## 判级别时查
+
+1. 结论是：通过、有条件通过、不通过。三者之一。
+2. 指出的问题写了文件。能定位到行的写了行。
+3. 结构喜好只算建议，不算严重。
+4. 建议最多三条，多的折成一句。
+
+## 报结论后查
+
+没有改代码，没有说「接下来改代码」「接下来验收」。

package/skill-files//345/256/241Java/references//347/244/272/344/276/213.md

@@ -0,0 +1,23 @@
+# 审 Java 的结论示例
+
+## 代码评审
+
+结论：不通过
+
+严重：
+
+- 已有 RefundService，这次又新建了 RefundServiceV2，而且没有改原来的类。
+- 证据：搜索命中 RefundService.java。调用是 RefundController 到 RefundServiceV2。
+- 风险：仓库里会有两套退款逻辑。
+- 改法：把新逻辑并进 RefundService 的原方法，删掉 RefundServiceV2。
+
+警告：
+
+- RefundServiceV2 里自己写了空白判断，仓库里已有 StrUtil.isBlank。
+- 改法：改用已有方法，删掉重复实现。
+
+建议：
+
+- 两个服务方法只有实体类型不同。可以以后抽公共转换，这次不挡。
+
+不要把「要不要用策略模式」写成严重。编译失败要写文件和行，有证据才算严重。

package/skill-files//345/256/241Java/references//347/272/246/346/235/237.md

@@ -0,0 +1,7 @@
+# 约束
+
+这里只写尽量做到的事。必须项在 `references/护栏.md`。
+
+## 尽量
+
+- 问题写清文件，能定位到行就写行。

package/skill-files//345/256/241Java/references//350/247/204/345/210/231.md

@@ -0,0 +1,23 @@
+# 审 Java 的规则
+
+只评这次 Java 改动。不改代码。不评文档齐不齐。不核对需求有没有做完。
+
+先看 diff，再用搜索核对。没有搜索到的证据，不要把结论升成严重。
+
+新建文件的类名如果以 Service、Controller、Facade、Manager、Helper、Handler、Wrapper、Biz、Core、Processor、Coordinator 结尾，先在仓库里搜同一职责。搜到了却没有扩展原类、又新建平行类，算严重。只是方法可以复用，算警告，写出原方法在哪。已有类被修改，不强制再搜一遍。
+
+自己又写一套判空、日期或字符串工具，而仓库里已有等价方法，算警告。
+
+同一个文件里有两处八行以上几乎一样的逻辑，算警告。
+
+新建类只包了一层转发，或简单增删改查包了三层以上，算警告。方法体只有一行转发，算建议。
+
+像「要不要用策略模式」这种结构喜好，只可以算建议，不要算严重。
+
+本仓库已有写法和这次 diff 冲突时，以仓库先例为准，并指出新代码哪里不一致。
+
+diff 涉及 SQL、事务、循环、并发、IO、异常日志、安全、接口参数时，读 `references/领域检项.md` 里对应的那一组，按组里的检项查。哪组都不沾的改动不用读。
+
+意见必须是简体中文。先说风险，再写文件和依据。不要用黑话。类名可以留，旁边说明它在重复什么。
+
+结论用：通过、有条件通过、不通过。

package/skill-files//345/256/241Java/references//351/242/206/345/237/237/346/243/200/351/241/271.md

@@ -0,0 +1,58 @@
+# 领域检项
+
+改到哪个领域，查哪一组。不全量读。每组先写「看到什么信号」，再写「查什么」。查到才报，查不到不凑数。
+
+## 数据库（看到 SQL、Mapper XML、批量操作时查）
+
+- UPDATE/DELETE 的 WHERE 能不能被绕过：动态条件全空时会不会全表执行。Java 侧有没有校验条件非空。
+- IN 参数有没有上限：单批超过 1000 会撞数据库限制。大集合优先改 JOIN，改不了要分批（`Lists.partition`）。
+- 有没有同表重复 JOIN、与结果集无关的子查询。过滤条件有没有下推到派生表内层。
+- 列表查询有没有分页或硬上限：LIMIT、分页插件、pageSize 上限，动态 SQL 每个分支都要有界。全量导出要走流式或游标。
+- 有没有 `SELECT *`。宽表应只取必要列。
+- 格式化、转换类计算有没有下推到 DB 函数。应在 Java 侧做。
+- 连接池参数：connection-timeout、max-lifetime、minimum-idle 配了没有。实例数乘池大小有没有超 DB 的 max_connections。
+
+## 事务（看到 @Transactional 或方法内多次写库时查）
+
+- 注解位置：是不是 Service 层 public 实例方法，类是不是 Spring Bean。类级注解、Controller、static、`new` 出来的对象，事务都不生效。
+- 写操作有没有显式 `rollbackFor = Exception.class`。默认只回滚 RuntimeException。
+- 同类 `this` 自调用不走代理：事务方法是不是被同类别的方法直接调的。
+- 事务方法内有没有 catch 吞异常不重抛：事务会照常提交。
+
+## 性能（看到循环体或集合处理时查）
+
+- 循环内查库（N+1）：改 JOIN 或批量 IN 加 `groupingBy`。
+- 循环内单条 insert：改 `<foreach>` 批量或 `saveBatch`。
+- 循环内调远程 API：改批量接口，没有批量接口应停下问，不是先写。
+
+## 并发（看到线程、线程池、共享状态时查）
+
+- 有没有裸 `new Thread()`：应统一用 `@Async` 加自定义 `ThreadPoolTaskExecutor`，或复用已有线程池。
+- 共享可变状态：单例 Bean 的可变字段、共享 `SimpleDateFormat`、check-then-act 非原子（改 `computeIfAbsent`）、双检锁字段没加 `volatile`。并发容器选型（`ConcurrentHashMap`、`CopyOnWriteArrayList`）。
+- `ReentrantLock.lock()` 后是不是紧跟 `try-finally`；`CountDownLatch.countDown()` 在不在 `finally`。
+- 多锁场景加锁顺序是不是全局唯一（如按 ID 排序）。`synchronized` 块内有没有调外部方法。
+
+## 资源泄漏（看到 IO、ThreadLocal、静态集合时查）
+
+- 资源是否 try-with-resources。
+- ThreadLocal 有没有在 `finally` 里 `remove()`。
+- 静态集合是不是裸 `static Map` 只增不删：缓存要用带淘汰策略的容器（Caffeine 的 `maximumSize` 加 `expireAfterWrite`）。集合承载唯一状态数据时要确认持久化方案。
+
+## 异常日志（看到 catch、log 调用时查）
+
+- 空 catch、只 `e.printStackTrace()`、只打 `e.getMessage()`。
+- 异常对象是不是 log 方法的最后一个参数（保证堆栈完整）。
+- 日志有没有业务上下文：userId、orderNo 之类，只有「失败」两个字没法定位。
+
+## 安全（看到 SQL 拼接、文件路径、加密、随机数时查）
+
+- `${}` 拼接：动态表名、排序列有没有白名单校验。
+- 路径拼接：有没有 `normalize()` 加 `startsWith(basePath)`。解压有没有防 Zip Slip。上传有没有扩展名白名单加重命名。下载路径是不是服务端映射。
+- 密钥、口令有没有硬编码：应走环境变量或配置中心。
+- 弱算法：MD5、SHA1、DES、AES-ECB。安全场景有没有用 `SecureRandom` 而不是 `new Random()`。
+- 反序列化：Jackson 的 default typing、Fastjson 的 autoType 有没有关。
+
+## 接口（看到 Controller、请求对象时查）
+
+- 参数校验：`@Validated` 加约束注解，或代码内手动校验，二者有其一。
+- 金额字段是不是 `BigDecimal`，比较是不是 `compareTo`。

package/skill-files//345/256/241/346/226/207/346/241/243/references//346/212/244/346/240/217.md

@@ -0,0 +1,18 @@
+# 护栏
+
+护栏挂在动作上，不靠回头翻清单。必须项只在这一份。`references/约束.md` 只是尽量项。
+
+## 开评前查
+
+1. 只看已经存在的文件。缺的文件点名，不要求补齐，也不因此判不通过。
+2. 纯后端变更里，页面类检项整体记不适用，不空转。
+
+## 判级别时查
+
+1. 结论是：通过、有条件通过、不通过。三者之一。
+2. 有接口设计时，还在用的接口少了请求参数、成功响应或业务错误任一张表，标成阻塞。表被写成一段话，同样标成阻塞。
+3. 两份文档冲突时，更具体的设计为准，并指出需求里哪一句要改。不两边各打一耙。
+
+## 报结论后查
+
+没有改文件，没有写代码，没有说「接下来改文档」。

package/skill-files//345/256/241/346/226/207/346/241/243/references//347/272/246/346/235/237.md

@@ -0,0 +1,8 @@
+# 约束
+
+这里只写尽量做到的事。必须项在 `references/护栏.md`。
+
+## 尽量
+
+- 问题条写清证据在哪一句、怎么改。
+- 设计里没有的章，不要要求补回空章。

package/skill-files//345/256/241/346/226/207/346/241/243/references//347/273/264/345/272/246.md

@@ -0,0 +1,17 @@
+# 审文档的七项
+
+只看已经存在的文件。缺的文件点名，不要因此判不通过，也不要要求补齐。
+
+给业务看的摘要用 3 到 5 句白话，不要用内部编号刷屏。问题条写：哪一项、证据在哪一句、怎么改。级别只用：阻塞、重要、建议。
+
+1. 合理性：做法和目标对得上，风险和回滚说得清，没有明显做不到的承诺。
+2. 完整性：会改变功能点的缺口有没有写成需求待定，而不是被猜掉。前端不在这个仓库时，功能点里的草图可以留，不要算漏了前端任务。有接口设计时，还在用的接口少了请求参数、成功响应或业务错误任一张表，标成阻塞。表被写成一段话，同样标成阻塞。
+3. 一致性：需求、设计、任务、用例互相不打架。两份都写了且冲突时，更具体的设计为准，并指出需求里哪一句要改。不要两边各打一耙。功能点句子和它下面的草图不一致时，以句子为准。设计里的页面原型和需求功能点对不上时，标成阻塞。
+4. 清晰：业务能看懂需求背景、需求描述、功能点拆分和设计概述。句子能单独成立。黑话要指出来，并写成完整中文该怎么改。
+5. 可测试：功能点能对上用例或看得见的结果。
+6. 可追溯：任务和用例能指回功能点原句。没有这些文件就跳过。
+7. 可维护：不做的事写在设计概述里。设计里没有的章，按这次不涉及处理。范围外的事就写不涉及。
+
+有没拍板、而且会改变功能点或实现的问题，标成阻塞。
+
+结论用：通过、有条件通过、不通过。

package/skill-files//345/256/241/346/226/207/346/241/243/references//350/270/251/345/235/221.md

@@ -0,0 +1,11 @@
+# 审文档踩坑
+
+目录下有多个变更、用户没点名时，先问看哪一个。
+
+缺文件只点名。不要把缺文件写成不通过，也不要替用户补一篇。
+
+两份文档冲突时，采用更具体的那份设计，并写出需求里要改的那一句。
+
+范围外写成「下一期」是错的。范围外就写不涉及。
+
+结论只留判断和要改的那一句。

package/skill-files//346/226/260/345/273/272/references//344/272/244/346/216/245.md

@@ -0,0 +1,11 @@
+# 新建之后怎么说
+
+这次只建目录。
+
+目录已经存在时，问是继续用这个目录，还是换一个名字。不要另外再建一个。
+
+命令失败就用白话说明原因，再附上命令返回的错误。不要假装已经建好。
+
+成功时只报路径：`freespec/<名称>变更/`。
+
+这个目录是这次变更的抽屉。里面一开始只有 `.freespec.yaml`。

package/skill-files//346/226/260/345/273/272/references//346/212/244/346/240/217.md

@@ -0,0 +1,14 @@
+# 护栏
+
+护栏挂在动作上，不靠回头翻清单。必须项只在这一份。
+
+## 建之前查
+
+1. 名称拿不准时问过了。
+2. 目录已经存在时，问过继续用还是换名，没有另建一个。
+
+## 报结果前查
+
+1. 命令退出码是 0 才说建好。失败用白话说明原因，附上命令返回的错误，不假装建好。
+2. 这次只建了目录，目录在 `freespec/<名称>变更/`。
+3. 对话只说明路径。不说「接下来写需求」。

package/skill-files//346/226/260/345/273/272/references//347/272/246/346/235/237.md

@@ -0,0 +1,7 @@
+# 约束
+
+这里只写尽量做到的事。必须项在 `references/护栏.md`。
+
+## 尽量
+
+- 名称用中文。用户没说「变更」时，原样传给命令，由命令补上。不要为了补这两个字再问一次。

package/skill-files//346/267/261/346/200/235/config/prompts.yaml

@@ -0,0 +1,114 @@
+# 往深处和旁边想时要看的漏洞。
+# 用户原话、已有材料或仓库已经能补上的，写进答案，不要出题。
+# 页面、表、接口对不上时，先点选以哪边为准，再出这里的题。
+# 实物不在这里。按 references/三方核对.md。
+# skip_if 成立就不要出这题。options 是点选项。
+# allow_multiple 为 true 时人可以点多项。Cursor 对应 allow_multiple，Trae 对应 multiSelect。
+# text 里的「这里换成…」出卡前换成仓库里看到的内容。没换成不要出这题。
+# 不要跑脚本。不替设计发明新的路径、错误码、表结构。
+
+layers:
+  - 范围
+  - 功能点
+  - 现状
+
+prompts:
+  - id: SCOPE-01
+    layer: 范围
+    header: 这次范围
+    text: 这次动哪一块？旁边容易被算成同一次的，要不要算进来？
+    skip_if: 用户原话、已有材料或需求描述里已经写了动哪一块，以及这次不动的相邻块
+    allow_multiple: false
+    options:
+      - id: named-only
+        label: 只动已经点名的那一块
+        description: 旁边的页面、表、接口这次不改。
+      - id: with-neighbor
+        label: 连同相邻的一块一起动
+        description: 出题前把相邻块的名字写进 label。看不出名字就删掉这项。删掉后不足两项，不要出这题，记已定，结论写「只动已经点名的那一块」，并写明没有看出第二块。
+
+  - id: SCOPE-02
+    layer: 范围
+    header: 从哪完成
+    text: 人从哪里完成这件事？
+    skip_if: 已经说明有页面、没有页面，或从哪里触发
+    allow_multiple: false
+    options:
+      - id: page
+        label: 有页面，人在页面上完成
+        description: 可以写多了或少了哪一块。不问按钮怎么摆、字段怎么放。
+      - id: called
+        label: 没有页面，别的系统调进来
+        description: 不问按钮和字段怎么摆。
+      - id: job
+        label: 定时或人在后台跑
+        description: 答案里写谁触发、跑完怎样、不跑时怎样。
+      - id: data
+        label: 只改数据或配置
+        description: 没有人点的入口。
+
+  - id: SCOPE-03
+    layer: 范围
+    header: 谁能看见
+    text: 做完之后谁能看出不一样？
+    skip_if: 用户原话、已有材料或功能点里已经写了谁看见什么
+    allow_multiple: false
+    options:
+      - id: operator
+        label: 只有操作的人能看出不一样
+        description: 别人的界面不变。
+      - id: another
+        label: 还有别人能看见
+        description: 材料里已经有角色名，就把名字写进 label。没有名字就留这句话，不要编一个角色。
+      - id: log-only
+        label: 人看不出来，只留记录
+        description: 答案里写留下什么记录。
+
+  - id: NOW-01
+    layer: 现状
+    header: 现有行为
+    text: 仓库里现在是「这里换成你看到的行为」。这次保持，还是改掉？
+    skip_if: 已经对照过现有实现，并写进答案
+    allow_multiple: false
+    options:
+      - id: keep
+        label: 保持仓库里现在的行为
+        description: 这次不改这段已经在跑的做法。
+      - id: change
+        label: 改成这次要的行为
+        description: 问句里要已经写上现在是什么样。没写上就不要出这题。
+
+  - id: FUNC-01
+    layer: 功能点
+    header: 异常情况
+    text: 失败、重复、没有数据，这三种里哪种这次要管？不管的不用点。
+    skip_if: 答案、功能点或需求待定里已经写了这三种
+    allow_multiple: true
+    note: 如果「三种这次都不管」和另外几项一起被点中，丢掉「三种这次都不管」，只记被点中的具体项。
+    options:
+      - id: fail
+        label: 失败要有人能看出来
+        description: 答案里要写失败时谁看见什么。
+      - id: retry
+        label: 重复提交要有确定结果
+        description: 同一次事情来第二次，结果要写明。
+      - id: empty
+        label: 没有数据要有确定结果
+        description: 找不到时谁看见什么，要写明。
+      - id: none
+        label: 三种这次都不管
+        description: 只在三种都不管时单选这一项。
+
+  - id: FUNC-02
+    layer: 功能点
+    header: 旧数据
+    text: 以前已经产生的数据，要不要一起改？
+    skip_if: 用户原话、答案或需求描述里已经写了历史数据
+    allow_multiple: false
+    options:
+      - id: migrate
+        label: 以前的数据一起改
+        description: 答案里要写旧数据变成什么样。
+      - id: leave
+        label: 以前的数据保持不动
+        description: 只影响这次新发生的。答案里写明旧数据不在这次范围内。