Technology Learning Judgment

技术学习判断

目标

培养技术决策能力，而不是记忆 API。解释足够的实现细节，使读者能识别技术提供的保证、不提供的保证、风险与适用性。将 AI 生成的代码和测试视为需要审阅的证据，而非需求已满足的证明。

保持材料聚焦。除非用户明确要求，否则不要把一份连贯的技术文档扩展成课程目录、穷尽式参考手册，或“一概念一文件”的练习集。

核心规则

对材料中的每一项技术主张，区分三个层次：

| 层次 | 要回答的问题 | 示例 | |---|---|---| | 框架能力 | 库或运行时实际做了什么？ | Checkpointer 保存图执行快照。 | | 系统要求 | 应用还必须补上什么？ | 外部副作用需要幂等键。 | | 业务保证 | 产品可以承诺什么？ | 一笔支付至多扣款一次。 |

绝不将框架能力写成系统或业务保证。

学习新技术的最小流程

1. 限定目标：明确要达到“会使用、能设计，还是能审阅 AI 交付”的哪一层；列出必要前置知识，并写明本次不覆盖的内容。
2. 建立最小可信资料集：优先使用官方概览/概念文档、架构或 API 文档、版本迁移说明；需要理解根本机制时再阅读源码、协议或原始论文。标注文档验证日期与版本范围。
3. 先建立最小概念地图：每个概念先回答“它是什么、解决什么问题”，再用一句话说明“输入 → 核心处理 → 输出”。术语表保持紧凑；后文再展开机制、源码和边界。
4. 建立一条详细的贯穿链路：概念速通后、专题讲解前，用一个现实且有代表性的示例串起尽可能多的核心概念。逐步展示输入、State/数据变化、调用的组件、路由、输出和失败/暂停点；不要只画概念箭头。后续专题持续回指这条链路。
5. 按本技能的“五个部分”深入选定主题：只讲与学习目标相关的能力，不为了完整而罗列功能清单。
6. 在概念中穿插组件讲解：首次使用具体类、方法、组件或配置时，先解释其归属、职责、输入、输出、读写的数据、生命周期/副作用和它在贯穿链路中的位置；再展示依赖该组件的代码。
7. 代码实战前复盘贯穿链路：用一段压缩的“输入 → 关键组件 → 状态变化 → 输出”回顾已学内容，并说明最终实战复用哪些组件、额外增加哪些真实约束。
8. 验证是否真正理解：对每个核心机制提出少量判断问题：能否复述输入到输出的流程？能否说明前提与失败方式？能否判断一个具体场景该不该使用它？能否识别 AI 方案中“表面实现、实际未保证”的部分？

不要把验证等同于大量练习文件。除非用户需要动手教学，否则用流程复述、反例和技术选型判断来验证理解。

审阅或写作流程

1. 确定读者、前置知识、文档目标和版本边界。若 API 行为、弃用状态或产品建议可能变化，断言前先用一手文档核验。
2. 对每个选定主题，只写下文五个部分；不增加与决策无关的内容。
3. 当该主题容易被滥用或与其他系统混淆时，补一个简短的“能力边界与替代方案”。
4. 用最少的修改改变读者的实际判断，不建议无关扩展。

一个主题的五个部分与组件卡

1. 定义与范围

说明机制是什么、解决什么问题；当有助于避免常见误解时，也说明它不是什么。

2. 输入到输出的运行流程

追踪最小而有意义的路径：

输入 → 状态或请求 → 执行决策 → 更新或副作用 → 输出/持久化结果

当共享状态、重试、分支或持久化使行为不直观时，使用紧凑的状态演化表。解释顺序和合并规则，不要只给流程图箭头贴标签。

3. 实现机制

解释支撑该行为的设计决策。仅在有助于理解机制时，使用一小段代码、伪代码或定向源码讲解。优先回答：

• 哪个数据结构被更新或持久化？
• 运行时何时提交、重试或恢复工作？
• 哪个函数拥有路由、合并、授权或副作用的职责？

不要粘贴框架内部实现，除非它能解释一个用户可见的保证或限制。

3.5 组件卡（首次出现时必需）

在代码首次使用一个关键类、方法、装饰器、组件或配置键之前，给出紧凑组件卡：

| 项 | 必须说明 | |---|---| | 名称与归属 | 它从哪个包/模块来，处于什么抽象层 | | 职责 | 它独自负责什么，不负责什么 | | 输入 | 参数、读取的 State/上下文、前置条件 | | 输出 | 返回值、写入的 State、发出的事件或异常 | | 生命周期 | 何时构造、何时调用、是否保存状态/产生副作用 | | 链路位置 | 它接收谁的输出，结果被谁消费 |

组件卡不是 API 参考手册：只覆盖当前链路和本节代码真正使用的符号。但不能以“无需背 API”为由跳过调用接口、输入输出或副作用的解释。

4. 使用建议与失效模式

给出操作规则、最重要的误用及其缓解方式。把要求写成可验证的断言。例如，不要只写“支持恢复”，应写成“使用同一执行标识恢复，并证明重跑被暂停节点不会重复产生外部副作用”。

5. 能力边界与行业替代方案

先描述问题类别，再选择技术。不要把 LangGraph、LLM 或任何偏好技术写成必须获胜的竞赛。

| 问题类别 | 常见选择 | 必须明确的边界 | |---|---|---| | 固定、短小、确定性处理 | 普通函数或服务代码 | 图不会增加控制价值，只会增加复杂度。 | | 长运行的业务流程和补偿 | Temporal/Cadence 或云工作流服务等持久化工作流引擎 | Agent 运行时不能替代领域事务和补偿。 | | 异步吞吐与可靠投递 | 队列、Worker、数据库 Outbox | Agent 编排不能替代投递保证。 | | 定时数据管道 | Airflow、Dagster、Prefect 或同类工具 | DAG 调度不同于交互式 Agent 状态。 | | 动态 LLM 工具调用、审批、恢复和状态化路由 | LangGraph 或构建于其上的高层 Agent 框架 | 工具权限、沙箱、审计和业务授权仍由应用负责。 | | 简单的工具型聊天 Agent | 高层 Agent 工厂 | 只有需要自定义状态、路由、恢复或治理时，才值得自建图。 |

只有当替代方案更好地解决同一需求时才提及它；“普通服务代码”是正确答案时，要直接写出来。

跨技术的重点核查项

只选取与当前主题相关的项；不要为了套模板而全部罗列。

• 状态与并发：更新语义、冲突规则、顺序保证和部分失败如何定义？框架内状态管理通常不等于数据库事务或跨服务一致性。
• 持久化与恢复：保存了什么、恢复粒度是什么、重试或恢复会重做什么？运行时快照通常不等于业务实体的事实来源。
• 外部副作用：发生超时、重复请求或恢复执行时，如何防止重复扣费、重复发信或重复写入？
• 权限与安全：技术组件负责执行什么，应用仍须独立负责什么？不要把工具调用、输入校验或身份认证写成最小权限、沙箱或业务授权。
• 数据与输出：校验的是格式、类型、来源还是事实？格式正确不代表结论正确、数据新鲜或有权使用。
• 扩展与可靠性：并行、缓存、重试、队列和限流分别提供什么保证，又会引入哪些成本、排序或失败语义？
• 抽象层级：高层封装、框架和底层原语各自隐藏了什么？需要定制时，代价是什么？

若材料讲述模型工具调用、插件或自动化流程，展示完整链路：输入或决策来源、受限执行、结果回流、停止条件、权限边界和资源限制。不要省略任一步后仍称其为端到端自动化能力。

Vibe Coding 验收视角

当用户把实现交给 AI 时，将宽泛主张转化为可审阅的问题：

• 持久化状态在哪里，由哪个精确的键进行作用域隔离？
• 发生重试、恢复、超时、重复投递或部分失败时会怎样？
• 哪条代码路径在模型输出之外独立执行授权？
• 哪个不变量证明所宣称的属性，哪个测试覆盖失败路径？
• 这项技术是否必要，还是更简单的确定性组件已能满足需求？

不要要求读者记忆 API 签名。要教授机制和验收问题，使其能指定、审阅和调试 AI 生成的实现。

交付标准

以校准过的结论开头：哪些内容正确、哪些未验证、哪些被夸大、哪些暂缓。按对决策的影响排序修改建议。对当前 API 或迁移主张附上一手来源链接。没有核验相应条件时，不得声称示例“复制可运行”、生产就绪、安全、可恢复或属于行业标准。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zonji6
• Source: zonji6/technology-learning-judgment
• License: MIT

Install and usage instructions live in the source repository linked above.