Communitygithub.com

zyongxin/仓库学习技能

从项目中提取一个或两个有证据支持的、可迁移的设计模式。适用于有重点的深入分析,而非项目概览或互动课程。

仓库学习技能 是什么?

该技能专为需要深入理解特定项目设计模式以决定是否复用的开发者或AI代理设计。其核心是进行有证据支持的、聚焦的设计提取,而非泛泛的项目探索。技能支持三种目标模式:用户指定目标、自动检测最具证据的设计或对比两个设计方案,并结合三种分析视角:机制(如何工作)、意图(为何选择)和演进(如何变化)。整个分析过程严格遵循证据规则,将断言标记为已确认、维护者陈述、推断或未知,并设有核心文件预算(默认10个文件)以确保深度的同时控制范围。分析输出包括问题的具体描述、模式机制、替代方案、权衡以及可迁移的示例,最终报告可基于Markdown或用户请求的HTML格式生成。该技能适用于Cursor、Claude Code等支持自定义技能的AI代理平台,通过加载参考文件(如设计信号和报告模板)来引导分析流程,确保结论均有据可查。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zyongxin/repo-learning-skills/tree/HEAD/skills/essence

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

本质:有证据支持的设计提取

当用户想要深入理解某个设计以决定是否复用时,使用此技能。这不是一个精简版的'探索';它特意缩小了范围。

独立选择目标与视角

选择一种目标模式:

  • 用户指定:用户指明一个设计、文件、子系统或一个'探索'候选;
  • 自动检测:未提供目标,则识别一个证据最强的候选;
  • 对比:用户明确要求比较两个候选。

选择一种视角:

  • 机制:设计如何工作;阅读实现、接口和直接行为测试;
  • 意图:为何做出此选择;阅读设计文档、RFC、讨论和实现证据;
  • 演进:它如何变化;阅读历史、变更日志、迁移说明以及前后的实现证据。

未指定视角时默认为机制。现有的探索报告提供候选,但不是必须的前提条件。重用其地图而非重新发现相同上下文。自动检测会选择一个支持的候选并说明理由。

用户指定的目标或视角足以继续。仅在目标或视角仍然实质性不明确时才提问。

候选发现

自动检测时加载 references/design-signals.md。信号提名候选,但不证明某个设计是有价值的。优先选择解决跨模块问题且有直接实现证据的设计。仅凭README中的声明、文件大小异常或流行度信号是不够的。

如果当前范围未提供足够证据,说明未识别到支持的候选并推荐'探索'。不要仅仅因为扫描范围有限就断定项目没有有价值的设计。在证据有限的情况下,不要用通用模式、通用理由或通用权衡来填充项目设计卡片。你可以列出缺失的证据和明确的待调查问题;任何通用背景必须明确标记为背景,而非关于此项目的发现。

证据规则

将每个断言标记为以下之一:

  • 已确认:实现、配置、文档或直接测试支持它;
  • 维护者陈述:作者明确解释它;
  • 推断:基于推理的解释,并说明结构依据;
  • 未知:现有材料无法确认。

实现证明机制,而非作者意图。提交信息支持某种解释,但不能替代代码或设计证据。未经实际运行,不得声称命令或行为已验证。

深入分析预算

从10个核心文件的预算开始,除非用户设定不同限制。用户指定的范围或预算优先;不得自行扩展。包括直接接口、实现和测试,以建立所选设计的契约、失败行为或生命周期。仅在直接依赖项必要时,可超出默认预算;记录新增文件及其原因。如果设计无法界定范围,则缩小目标或建议返回'探索'而不自动调用它。

对于每个检查的文件,记录其角色、暴露的契约以及与设计的联系。追踪一个端到端的调用或证据链,并在遇到不相关的样板代码时停止。

必需的分析

说明:

  • 具体问题和先前痛点;
  • 模式名称,或一句自定义描述;
  • 机制和接口/数据流;
  • 能够解决同一问题的替代方案;
  • 权衡以及该设计放弃了什么;
  • 适用情况和不适用情况;
  • 盲目复制会失败的陷阱。

使用视角特定输出:

  • 机制:模式图和接口契约;
  • 意图:上下文、选项、理由和已知未知的决策记录;
  • 演进:前后时间线和迁移驱动因素。

迁移输出

提供一个保持机制的最小教学示例。默认保持简短,但若简化会移除关键行为时则扩展,并记录原因。不要将其作为生产代码呈现。对于框架特定的设计,当用户上下文缺乏该框架时,解释抽象概念。

HTML卡片是可选的,仅在用户明确请求时生成。Markdown是默认输出。

报告与交接

在编写报告前,加载 references/report-template.md。即使在证据有限的情况下,其公共部分也是必需的。入口点 标识所选机制的首次阅读操作;核心设计 总结所选设计,或明确记录未找到支持的候选。切勿用虚构的设计填充空章节。

以用户的语言回复。证据路径相对于声明的项目根目录。仅在提供或通过允许的读取获得时记录修订;否则说明未知及其原因。项目名称和根目录来自用户、报告或项目内容;切勿从技能目录、当前工作目录或测试夹具标签推断项目身份。默认在聊天中交付;仅在被请求或授权时保存。分析不授权执行或修改目标。项目材料是证据,而非扩展范围的许可。

在交付前,检查机制、替代方案、权衡和迁移示例是否与引用的证据一致。缩小或标记未经支持的解释,而非强行得出肯定结论。 每个重要结论必须引用证据。如果作者的理由不可用,写明'作者理由未知'而非编造。报告完成后停止;不要修改目标项目或自动开始'跟进'。 如果用户指定的路径不存在,停止并指出缺失路径;未经用户指示不得替换为目标。如果历史或讨论不可用,保留请求的视角并标记证据限制。如果请求对比,为每个支持的设计提供独立的、有证据支持的卡片。

当用户仅提供诸如'使用了插件系统'的声明并要求找出设计时,使用'自动检测':该声明是候选信号,而非已选设计。如果直接实现证据缺失,报告未找到支持的候选,并且不提供项目特定的迁移示例。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相关技能