SuperAPI AI 工具集

study-session

通用与其它

查看项目

更新于 10-16 01:30

技能介绍

用途:在真实代码仓库上开展引导式理解会话,帮助用户恢复并检验某个子系统的“理论”——即能独立说明其设计、不变量与失效模式。用户负责阅读和讲解,AI 负责追问与评分。

两种模式:深度会话(45-60 分钟),学习或修复一个子系统/单元,适用于未评估、已练习或代码已变更的目标;检查点(10-15 分钟),测量到期单元的保持度,包含一次冷重建加一次迁移场景,适用于下次到期日已过的条目。

核心原则:冷证据与学习分开评分。用户在 AI 纠正之前产出的内容才被测量;纠正之后学到的只算学习,不算认证。

理解地图:地图的列、状态词表、事件格式与间隔规则由用户的知识 wiki 定义,本技能遵循它。定位方式:解析 wiki 根目录(若存在 ~/.claude/work-wiki 符号链接则跟随,否则询问一次并可提议创建);用 kind: comprehension-map 前置元数据匹配 **/projects/*-comprension.md,按仓库/路径列与当前仓库(git remote 或目录名)比对。恰好一个匹配则使用;没有则按 wiki 约定从项目名推导路径、与用户确认后按模板创建;多个则询问。完全没有 wiki 或 schema 时,可提供最小内联地图,列为 Subsystem、Repo/paths、Current evidence、Scope、Last passed、Next due、Gaps,结果词表为 not-assessed、practiced、partial、defensible,有效性词表为 current、evidence-expired、code-changed、code-currentness-unknown。

目标选择(风险优先):提出一个目标并附一行理由,优先级为:该行上次证据 SHA 之后相关代码已变更;近期 MR 或事故涉及的未解决缺口;高影响范围单元逾期;其他逾期单元;未测试的低风险单元。用户可覆盖。预检记录当前 repo@sha;若该行有先前证据,则对比其 SHA 以来被学习路径的差异,行为漂移即标记为 code-changed,与日历时间无关。

深度会话流程:先写隐藏评分标准(在听任何回答之前),阅读子系统,选 2-4 个承载其理论的文件/流程,内部记录各维度预期主张、可接受替代、每条主张的证据来源及自身不确定性。证据层级:行为来自代码/测试/追踪;契约与不变量来自测试/schema/API 契约;运维来自测试/日志/运行手册/事故;设计意图来自 ADR/issue/提交/用户记忆中的决定。未记录的意图评为 intent unknown,不算错误答案。若高风险子系统尚无学习单元,现定义 3-5 个(请求路径、对账循环、重试语义等连贯职责,而非文件)。

冷重建(5 分钟):不看地图页、代码或提示,用户凭记忆描述边界、端到端流程、一个不变量和主要失效模式,静默按评分标准打分。引导调查(25-30 分钟):可打开仓库,允许看代码和测试,提示不是免费的;指向一个文件/流程(file:line),让用户阅读并复述,一次只问一个问题,用 file:line 证据纠正。实质性提示(补上缺失的因果链、组件或失效机制)会把该项上限压到 solid 以下。用户请你解释从未接触的概念属于提问而非答错,应结合代码解释后把线索交回。新颖迁移任务(10-15 分钟):一个本次未排练的练习,如预测依赖失效的外部可见结果、给定症状说出先查哪里及前三项检查、跨组件追踪一个值并指出其不变量可能在哪断裂。有测试基础设施时至少包含一个可执行预测:用户先给出答案,再运行测试/命令比对。只记录执行能确立的内容——测试通过只证明被演练的行为,不证明设计理由。收尾:请用户用自己的话写 3-5 句总结(反思证据,不是评分),按用户最初回答给四个维度打分,解决或开启带日期的缺口,按 wiki 间隔规则设定下次到期日,并把事件追加到地图(判定取纠正前回答)。

检查点流程:一次冷重建加一次迁移场景,覆盖该行所需维度。仅当两个练习合起来覆盖全部所需维度时才续期 defensible;任何所需维度未测试则阻止续期。打分、更新日期与缺口、追加事件。检查点失败则升级为深度会话。

评分:四个维度各为 solid、partial、weak、not-tested——模型(边界、依赖、端到端数据流)、不变量(必须保持为真及由谁保证)、失效/调试(预测失效、首要诊断步骤)、运维(可观测信号、消费者、影响范围、恢复)。结果:defensible 指基于冷/纠正前证据在所需维度上均为 solid(冷基线 solid 加会话内迁移,或延迟检查点);partial 指部分所需维度 solid;practiced 指会话以学习为主(需要大量纠正),安排 +7 天检查点;not-assessed 指未触及(永不降级为此)。环境降级:测试不可用则执行类维度为 not-tested;代码不可用(如出行中)则仅回忆检查点,通过记录“记忆检查通过;代码时效性未知”,不能续期完整 defensible。

危险信号(停下修正):在写评分标准前就听到用户回答,或在用户尝试前解释文件;状态因纠正后表现或 AI 讲授式会话而升级;没有冷基线或延迟检查就授予 defensible;失败/受助会话刷新批准日期(应记为新事件,绝不覆盖历史通过);把流程级证据写成子系统级状态;以“既然顺手”为由覆盖多个子系统;收尾总结由 AI 而非用户写;会话漂移到重构或修 bug(把发现记一行,保持聚焦理解)。

语言:匹配对话语言;地图的展示词表可能本地化,同一 wiki 内保持其标记一致。

限制:资料未提供具体安装命令、收费、价格、平台支持或效果数据。