这一页不是笔记,是待办清单:五条可以直接粘进 Claude Code 的提示语,对应 uparty 当前最该修的五件事。
每条都按同一个结构写:背景(为什么要做)→ 任务 → 要求 → 禁区 → 验收。这个结构本身比内容更重要——交任务前答不出"目标是什么、什么绝对不能改、怎么算做完了"这三问,就说明还没想清楚。 做完一条 /clear 再做下一条。
建议的执行顺序
拿不到编译信号,加再多 skill 都是空的
先修编译,再建工具顺序不能反
按编号做的话顺序是 2 → 1 → 3 → 4 → 5。
第 2 条(修 mvn compile)必须排在最前面。当前项目的处境是:编译崩溃 → 起不了服务 → 功能验证被迫只能查数据库反推。这意味着分层验证体系里最底下那一格是空的——秒级反馈根本不存在。
在拿到"编译通过"这个最基本的信号之前,再加多少 skill,验证链条最底下那格还是空的。Redis skill、SQL EXPLAIN skill 的价值都要等这一条做完才真正兑现。
每条单独开一个会话,做完 /clear 再开下一条。 这几个任务之间没有依赖(第 5 条复用第 4 条现成的 db.py),混在一个会话里只会互相污染上下文。
一、Apifox token 治理
已泄露到外部对话,需先轮换
明文凭据 + 文件自相矛盾P0 · 安全
.claude/skills/apifox-sync/SKILL.md 顶部的配置表里明文写着 Apifox access token 的值,而同一个文件第 131 行自己写着「严禁把 token 明文写入命令、文件或输出」。
好的一面:.gitignore 里有 .claude/*,git ls-files .claude/ 返回空,确实没进版本库。坏的一面:它已经被读进过外部对话上下文,该 token 必须先去 Apifox 后台轮换。
参照物是现成的——同目录下 uparty-test-db/scripts/db.py 的做法就是对的:不硬编码,运行时现读,文档里只说"去哪取"。
P0
提示语 1:Apifox token 治理
背景:.claude/skills/apifox-sync/SKILL.md 顶部的配置表里明文写着 Apifox access token 的值,
而同一个文件第 131 行自己写着「严禁把 token 明文写入命令、文件或输出」——自相矛盾。
该 token 已经泄露到外部对话上下文中,我会另行去 Apifox 后台轮换。
任务:把 apifox-sync 的凭据管理改成和 .claude/skills/uparty-test-db/scripts/db.py 一致的模式。
db.py 的做法是对的:不硬编码密码,运行时从 application-test.yml 现读,SKILL.md 里只描述"去哪取"。
要求:
1. 从 SKILL.md 里删除 token 明文值,改为:优先读环境变量 APIFOX_ACCESS_TOKEN;
若未设置,则从 ~/.uparty/apifox-token 读取(文件不存在时明确报错并告诉用户怎么创建)
2. 文档里保留"token 失效了去哪里重新生成"的说明
3. 检查 .claude/skills/ 下所有文件,确认没有其它明文凭据残留(db.py 的做法不用改)
禁区:
- 不要把任何真实凭据写进仓库任何文件
- 不要改动 apifox 的导入逻辑和覆盖策略部分
- 不要动 uparty-test-db 这个 skill
验收:grep -rn "afxp_" .claude/ 返回空;按新文档的说明能正常跑通一次同步。
二、定位 mvn compile 崩溃
排查顺序写进提示语,免得它瞎试
整条链路最底层的阻塞P0 · 价值最大
uparty-test-db/SKILL.md 里记着一句话:「本仓在此机器上 mvn compile 会因 javac 崩溃,起不了服务,所以功能验证主要走 DB 层。」
"走 DB 层"不是一个选择,是被迫降级——用数据的最终状态反推行为对不对,中间过程全靠猜。
提示语里我把排查顺序写死了(先拿崩溃日志 → 报版本 → 模块二分 → 文件二分 → 方案对比),因为这类问题最容易变成"换个参数再试一次"的盲目撞墙。
P0
提示语 2:定位 mvn compile 崩溃
背景:本仓在这台机器上 mvn compile 会导致 javac 崩溃,起不了服务,
导致所有功能验证被迫降级到"只能查数据库反推"。这是当前研发链路里最底层的阻塞:
连"编译通过"这个最基本的验证信号都拿不到。
任务:定位崩溃的根因,给出可执行的修复或绕过方案。
排查顺序(按这个顺序做,不要跳步):
1. 先完整复现一次,把 javac 的崩溃输出(含 hs_err_pid*.log 或 Crash 堆栈)完整保存下来,
贴出关键部分。先看清楚是 OOM、StackOverflow,还是 javac 内部 assertion/NPE。
2. 报告当前 JDK 版本(java -version、mvn -v)和 pom 里的 source/target(现在是 1.8)。
如果是已知的 javac bug,先查这个版本号对应的已知问题。
3. 如果崩溃与具体代码有关:用模块二分定位。
先 mvn compile -pl <单模块> 逐个模块跑,找出是哪个模块触发;
再在该模块内二分(临时移出部分源文件)定位到具体文件。
注意:这一步只在本地工作区做,定位完必须还原,不要提交任何临时改动。
4. 给出方案对比:换 JDK 小版本 / 调整编译参数(如 -J-Xmx、关闭特定 lint)/ 修改触发问题的源码,
分别说明改动面和风险。
禁区:
- 不要为了"能编译过"就删改业务代码逻辑
- 不要改 pom 里的依赖版本(Spring Boot 2.3.2 的升级是另一件事,本次不碰)
- 不要提交任何用于二分定位的临时删改
验收:mvn compile 能完整跑通;把根因和最终方案写进 docs/,
并在 .claude/skills/uparty-test-db/SKILL.md 里把"编译会崩所以只能走 DB 层"那段更新掉。
三、更新 CLAUDE.md 的角色描述
它会以为自己只审不写
一句过时的话会改变 AI 的行为P0 · 五分钟
CLAUDE.md 第 11 行写着「我主要用 Codex 写代码,用 Claude Code 做 Review」。
这句现在是错的,而且它会实质改变行为——读到这句,Claude 会默认自己的职责是审查而非实现,在被要求写代码时偏向"给建议"而不是直接动手。
项目约定文件里过时的描述,比没有描述更糟。
P0
提示语 3:更新 CLAUDE.md 角色描述
CLAUDE.md 第 11 行写着「我主要用 Codex 写代码,用 Claude Code 做 Review」,这已经过时了——
我现在基本全部用 Claude Code,既写代码也做 review。
任务:更新这段角色描述,改成:Claude Code 同时承担实现和审查;
并补充我期望的工作节奏(改动前先出 PLAN 等人确认、Minimal Diff、每次改动附验证方式)。
禁区:只改这一段角色描述和工作节奏,不要顺手重构整份 CLAUDE.md 的其它章节。
四、Redis 测试 skill
401 个文件用 Redis,key 规则散落各处
价值不在"能连",在那张 key 地图P1
实测:401 个 Java 文件在用 Redis,而 CacheKey 常量散落在各模块——uparty_admin/CacheKey.java、uparty_room/.../RoomRedisKey.java、uparty_marketing/.../BackgroundCacheKey.java、RankingListDataCacheKey.java……
所以这个 skill 的价值不在"能连能查"(那是 redis-cli 就能干的),而在于把散落的 key 规则汇成一张 AI 可用的地图。没有这张地图,只能瞎 SCAN。
核心用途是缓存一致性核对:改完库之后缓存有没有失效——这是这类项目最高发的一类 bug,而且查 MySQL 查不出来。
P1
提示语 4:Redis 测试 skill
背景:项目里有 401 个 Java 文件在用 Redis,CacheKey 常量散落在各模块
(uparty_admin/CacheKey.java、uparty_room/.../RoomRedisKey.java、
uparty_marketing/.../BackgroundCacheKey.java、RankingListDataCacheKey.java 等)。
现在验证功能只能查 MySQL,查不了缓存状态,而"改了库但缓存没失效"是这类项目最高发的一类 bug。
任务:新建 .claude/skills/uparty-test-redis/,完全照 uparty-test-db 的模式来
(SKILL.md + scripts/redis_cli.py),让 Claude 能在测试环境核对缓存状态。
必须包含:
1. 连接:测试环境 Redis,host/port/database 从 application-test.yml 读,不硬编码密码。
database 号写死为配置里的值,避免连错库。
2. key 命名地图:扫描仓库里所有 CacheKey / RedisKey 常量类,提取 key 前缀和含义,
在 SKILL.md 里列成一张表。这是这个 skill 最核心的价值——否则只能瞎 SCAN。
3. 只读命令默认放行:GET/HGETALL/TTL/TYPE/SCAN/ZRANGE 等。
4. 遍历必须用 SCAN,严禁 KEYS *(共享测试实例上会阻塞,影响其他人)。
5. 写操作必须 --write 且先要用户确认,和 db.py 保持一致。
6. 硬禁止清单(任何情况都不执行):FLUSHDB、FLUSHALL、CONFIG SET、
以及删除非本次测试账号相关的共享 key。
7. 典型用法示例:改完 DB 后核对对应缓存是否已失效。
禁区:
- 不要把 Redis 密码写进任何文件
- 不要修改 uparty-test-db 这个 skill
- 不要在生产环境配置上做任何事,只针对测试环境
验收:能用测试账号(user_id 2000000)跑通一次"查 key → 看 TTL → 确认缓存状态"的完整流程,
并在 SKILL.md 里留下这个示例。
五、SQL EXPLAIN skill
规范里的硬要求,现在全靠人肉
把人工判断变成自动信号P1 · 收益仅次于修编译
docs/代码审核规范.md 里有一条硬要求:「每条新增 SQL 说得出走哪个索引、扫多少行;无 N+1、无全量加载」。
但现在这条完全靠人判断,review 时经常只能写"未发现问题"——而规范自己还专门写了"性能一栏不许只写未发现问题"。
这条要求完全可以工具化:连测试库直接 EXPLAIN,把"扫描行数、是否走索引、有没有 filesort"变成机器可读的结论。这是把人工判断挪进机器可裁决的范围,正是那个"分层验证体系"的思路。
P1
提示语 5:SQL EXPLAIN skill
背景:docs/代码审核规范.md 要求「每条新增 SQL 说得出走哪个索引、扫多少行;
无 N+1、无全量加载」,但现在这条全靠人肉判断,review 时经常只能写"未发现问题"。
任务:新建 .claude/skills/uparty-sql-explain/,把这条要求变成可自动执行的检查。
必须包含:
1. 输入:一个 SQL(或一个 mapper xml / 注解里的 SQL),自动去测试库跑 EXPLAIN。
2. 输出结构化结论:是否走索引、走的哪个索引、预估扫描行数、有没有 filesort / temporary、
是否全表扫描。
3. 给出判定标准(写进 SKILL.md):什么情况算通过、什么情况必须打回。
例如:type=ALL 且表行数超过阈值 → 打回;出现 Using filesort 且分页 → 必须说明。
4. 复用 uparty-test-db/scripts/db.py 的连接方式,不要重新实现一套连接逻辑。
5. 只读:这个 skill 永远不执行任何写操作。
禁区:
- 只连测试库,绝不连生产
- 不要执行被检查的 SQL 本身(只跑 EXPLAIN)
- 不要改动 uparty-code-review 这个 skill 的流程(后续再决定怎么挂接)
验收:拿最近一次需求改动里新增的 SQL 跑一遍,输出上述结构化结论。
这一页之后还剩什么
按分层验证体系排
做完这五条,还有三层没建待办,不在本页提示语里
这五条做完,秒级反馈层才刚补上一半(编译能跑了,单测仍然接近于零)。剩下的按优先级:
- 补核心链路测试
- 收益结算、支付充值、开户、地区配置。不追覆盖率,只挑「改动频率 × 出错代价」最高的几条线。新代码强制带测试,33 万行存量一律豁免。
- MQ skill
- 项目有 mq/consumer 和 mq/producer,现在造一条消息、看消费结果只能靠人。
- 接口调用 skill
- 能真正带鉴权调一次接口,而不是只从 DB 反推行为。
- 日志 / 链路查询
- 现在线上出问题,AI 完全瞎,只能靠人去看。
- uparty-verify 总入口
- 把「编译 → 单测 → DB 核对 → Redis 核对 → 接口调用」串成一条可执行的链,并明确每层失败时该停还是该继续。这才是让 coding 这个工位「独立转起来」的那根线。
- 四份规范文档合并
- CLAUDE.md + AGENTS.md + 代码实现规范要求.md + 需求模板.md 共 20,641 字节,内容重叠且有冲突(「禁止 try-catch」只在其中一份,而实际 904 个文件在用)。三份规范等于没有规范。
它解释不了什么
这些提示语是给 uparty 这一个项目写的。 里面的路径、文件名、模块名、账号都是具体的,换个项目不能直接用——但那个「背景 → 任务 → 要求 → 禁区 → 验收」的结构可以照搬。
提示语写得再好,也替代不了验收。 尤其第 2 条和第 4 条会实际改动文件,跑完必须自己看 diff。
第 2 条可能定位不出来。 javac 崩溃有时是环境特异的(JDK 小版本、内存、特定依赖组合),不一定能在一轮里解决。如果它连试三次没进展,应该停下来换思路,而不是继续换参数。
这一页会随着执行进度作废——做完的条目应该删掉,不是留在这里。它和站里其他页的性质不同:其他页讲的是长期成立的东西,这一页只是一份有保质期的待办。