easysdd-learning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-learning

每次做 feature 或修 issue 都会留下 spec 文件——

{slug}-design.md

{slug}-fix-note.md

这些。但 spec 记录的是"做了什么"和"怎么做的"，不会记录"踩了什么坑"和"发现了什么更好的做法"。

没有沉淀的团队总在重复解决同一个问题。第一次解决一个问题需要研究，记下来后下次几分钟就够。easysdd-learning 就是给每次非 trivial 的工程实践补一张"学习卡"。

两条轨道：

坑点轨道（pitfall）：记录遇到的问题、根因、解法，防止下次再掉进同一个坑
知识轨道（knowledge）：记录发现的最佳实践、工作流改进、可复用模式

两者都写入沉淀目录

easysdd/compound/

（与其他沉淀子技能共享一个目录，分类规则看

easysdd/reference/shared-conventions.md

第 1 节"归档类文档"），格式统一，可被未来的 AI 和人类检索。本技能产出的文档在 frontmatter 里带

doc_type: learning

，文件名形如

YYYY-MM-DD-learning-{slug}.md

（日期打头、类型段固定为

learning

），这是本技能在共享目录里的身份标识。

Every time you work on a feature or fix an issue, you leave behind spec files — such as

{slug}-design.md

{slug}-fix-note.md

. However, spec documents record "what was done" and "how it was done", and do not record "what pitfalls were encountered" or "what better practices were discovered".

Teams without knowledge retention keep solving the same problem repeatedly. It takes research to solve a problem the first time, but only a few minutes the next time if it's documented. easysdd-learning is designed to add a "learning card" for each non-trivial engineering practice.

Two tracks:

Pitfall Track: Record the problems encountered, root causes, and solutions to avoid falling into the same pitfall next time
Knowledge Track: Record discovered best practices, workflow improvements, and reusable patterns

Both tracks are written to the archive directory

easysdd/compound/

(shares the same directory with other archive sub-skills, see Section 1 "Archived Documents" in

easysdd/reference/shared-conventions.md

for classification rules), with a unified format that can be retrieved by future AI and humans. Documents produced by this skill include

doc_type: learning

in the frontmatter, and filenames follow the pattern

YYYY-MM-DD-learning-{slug}.md

(starting with date, fixed type segment as

learning

), which serves as the identifier for this skill in the shared directory.

什么时候触发

When to Trigger

下面任一条件满足就触发：

情境	说明
完成一个 feature 工作流	`easysdd-feature-acceptance` 按 `easysdd/reference/shared-conventions.md` 主动问"要记录这次的学习点吗？"
完成一个 issue 工作流	`easysdd-issue-fix` 按 `easysdd/reference/shared-conventions.md` 主动问"要把这个坑记录下来吗？"
用户主动触发	"记录一下"、"沉淀知识"、"learning"、"document learnings" 等
解决了一次性难题	不在 feature / issue 工作流内，但花了大量时间才解决的工程问题

主动推荐时一句话即可，语气轻松。用户说"不用了"立刻跳过，不再提——重复推可能让用户觉得 AI 在加戏。

Trigger if any of the following conditions are met:

Scenario	Description
Completing a feature workflow	`easysdd-feature-acceptance` proactively asks "Would you like to record the learnings from this work?" according to `easysdd/reference/shared-conventions.md`
Completing an issue workflow	`easysdd-issue-fix` proactively asks "Would you like to record this pitfall?" according to `easysdd/reference/shared-conventions.md`
User initiates actively	Phrases like "record this", "document knowledge", "learning", "document learnings", etc.
Solved a one-time difficult problem	An engineering problem that took significant time to solve, but is not part of a feature / issue workflow

Use a single, casual sentence when proactively recommending. Immediately skip if the user says "no" — repeated prompts may make the user feel the AI is overstepping.

两条轨道各写什么

What to Write for Each Track

坑点轨道适用于：调试过的 bug、绕过的配置陷阱、环境问题、集成失败……一切"本来应该好但没好"的经历。

知识轨道适用于：发现的最佳实践、工作流改进、架构洞见、可复用的设计模式……一切"以后应该默认这样做"的学习。

两条轨道的 frontmatter、正文模板和完整示例已拆到同目录

reference.md

。本技能正文只保留判断与流程规则。

Pitfall Track applies to: Debugged bugs, bypassed configuration traps, environment issues, integration failures... all experiences where "things should have worked but didn't".

Knowledge Track applies to: Discovered best practices, workflow improvements, architectural insights, reusable design patterns... all learnings that "should be the default approach going forward".

The frontmatter, body templates, and complete examples for both tracks have been moved to the same directory's

reference.md

. This skill's documentation only retains the judgment and process rules.

工作流阶段

Workflow Phases

Phase 1：识别来源（自动）

Phase 1: Identify Source (Automatic)

从当前对话上下文提取：

来源类型：feature 工作流 / issue 工作流 / 独立问题
关联产物：feature 目录路径 / issue 目录路径（如有，供文档"来源"字段引用）
粗分轨道：坑点 or 知识。判断依据——"修了什么坏了的东西" = 坑点；"发现了什么更好做法" = 知识。两者都有就分两条写。

来源不明确就问用户一个问题澄清，不要猜。

Extract from the current conversation context:

Source Type: Feature workflow / Issue workflow / Independent problem
Associated Artifacts: Feature directory path / Issue directory path (if available, for reference in the document's "Source" field)
Initial Track Classification: Pitfall or Knowledge. Judgment criteria — "fixed something that was broken" = Pitfall; "discovered a better approach" = Knowledge. Write two separate documents if both apply.

Ask the user one clarification question if the source is unclear, do not guess.

Phase 1.5：查重叠与意图分流（必做）

Phase 1.5: Check for Duplicates and Intent Diversion (Mandatory)

按

easysdd/reference/shared-conventions.md

§6 第 5 / 6 条执行：

用户话里含"改 / 更新 / 补充 / 某条 learning"或明确指向某份旧文档 → 直接走更新已有条目路径
否则用下面"搜索工具"里
```
--filter tags~=
```
或
```
--query
```
查一遍本次主题 / 组件，命中相近旧文档时把候选列给用户，让用户选：更新 / supersede / 确实不同主题

更新路径：读旧文档 → 和用户对齐要改哪几节（常见是补充新踩的坑、补上当时"没找到原因"的根因） → 起草 diff → 写回原文件，补

updated: YYYY-MM-DD

，不新建文件。

Follow Section 6, Items 5 / 6 in

easysdd/reference/shared-conventions.md

If the user mentions "modify / update / supplement / a specific learning" or explicitly points to an old document → directly take the update existing entry path
Otherwise, use the "Search Tool" below with
```
--filter tags~=
```
or
```
--query
```
to search for the current topic / component. If similar old documents are found, present the candidates to the user and let them choose: Update / Supersede / Truly different topic

Update Path: Read the old document → align with the user on which sections to modify (common scenarios include adding newly encountered pitfalls, filling in the root cause that was "not found at the time") → draft the diff → write back to the original file, add

updated: YYYY-MM-DD

, do not create a new file.

Phase 2：提炼要点（和用户对话）

Phase 2: Refine Key Points (Dialogue with User)

一次一个问题，不要给用户一张大表格让他填。

坑点轨道问：

"你最开始观察到的现象是什么？"
"哪些解法试过但没用？"（鼓励写，即使觉得"没什么"——失败的尝试是后人最宝贵的信息，知道哪条路不通能省下大量时间）
"最终是怎么发现真正原因的？"
"下次可以更早发现吗？怎么发现？"

知识轨道问：

"你发现的这个模式，在什么情境下最有价值？"
"不这样做会出什么问题？"
"有没有不适用的反例？"

用户对某个问题说"没什么"或"跳过"就跳过——文档宁可少一节也不用空话填充。

Ask one question at a time, do not give the user a large form to fill out.

For Pitfall Track, ask:

"What was the initial phenomenon you observed?"
"Which solutions did you try that didn't work?" (Encourage users to write this even if they think it's "nothing" — failed attempts are the most valuable information for future team members; knowing which paths don't work saves a lot of time)
"How did you finally identify the real root cause?"
"Could this be detected earlier next time? How?"

For Knowledge Track, ask:

"In what scenarios is this pattern you discovered most valuable?"
"What problems would arise if this approach is not followed?"
"Are there any counterexamples where this doesn't apply?"

Skip a question if the user says "nothing" or "skip" — it's better to have fewer sections than to fill the document with empty words.

Phase 3：确认内容（AI 起草，用户 review）

Phase 3: Confirm Content (AI Drafts, User Reviews)

AI 起草完整的 learning 文档（含 YAML frontmatter + 所有正文节）
一次性展示给用户 review
用户确认后写入文件；有修改就按用户意见调整再写

AI drafts the complete learning document (including YAML frontmatter + all body sections)
Show the full draft to the user for review at once
Write to the file after user confirmation; adjust according to user feedback if there are modifications

Phase 4：归档

Phase 4: Archive

新建路径：写入
```
easysdd/compound/
```
，文件命名
```
YYYY-MM-DD-learning-{slug}.md
```
（日期取归档当天，不是问题发生当天），frontmatter 顶部带
```
doc_type: learning
```
（见
```
reference.md
```
）
更新路径：写回 Phase 1.5 定位到的原文件，frontmatter 补
```
updated: YYYY-MM-DD
```
supersede 路径：按
```
shared-conventions.md
```
§6 第 5 条处理新旧两份文件
写完后报告完整文件路径

New Document Path: Write to
```
easysdd/compound/
```
, filename follows
```
YYYY-MM-DD-learning-{slug}.md
```
(use the archive date, not the date the problem occurred), include
```
doc_type: learning
```
at the top of the frontmatter (see
```
reference.md
```
)
Update Path: Write back to the original file located in Phase 1.5, add
```
updated: YYYY-MM-DD
```
to the frontmatter
Supersede Path: Handle the old and new documents according to Section 6, Item 5 in
```
shared-conventions.md
```
Report the complete file path after writing

Phase 5：可发现性检查

Phase 5: Discoverability Check

写完后检查

AGENTS.md

或

CLAUDE.md

里有没有指引 AI 查阅

easysdd/compound/

沉淀目录的说明。没有就提示用户是否要加一行——别自作主张改文件，只提示，由用户决定。理由是 AGENTS.md 这种入口文件改动影响整个团队对 AI 的指引方式，用户该拍板。

After writing, check if

AGENTS.md

CLAUDE.md

contains instructions for AI to access the

easysdd/compound/

archive directory. If not, prompt the user whether to add a line — do not modify the file without permission, only prompt and let the user decide. The reason is that changes to entry files like AGENTS.md affect the team's guidance for AI, so the user should make the final call.

搜索工具

Search Tool

完整语法和示例见
easysdd/reference/tools.md
。本节只列 learning 特有的典型查询。

bash

undefined

Complete syntax and examples can be found in
easysdd/reference/tools.md
. This section only lists typical queries specific to learning documents.

bash

undefined

按轨道筛选坑点

Filter pitfalls by track

python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --filter track=pitfall --filter severity=high

按组件查相关学习点

Search for related learnings by component

python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --filter component~={组件名}

归档后查重叠

Check for duplicates after archiving

python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --filter tags~={主要 tag} --json

---

python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --filter tags~={主要 tag} --json

---

守护规则

Guardrails

归档类工作流共享守护规则（只增不删、宁缺毋滥、不替用户写、可发现性、归档后查重叠）见
easysdd/reference/shared-conventions.md
第 6 节。本技能特有规则：

不混入 spec——learning 文档不是 spec，不放进
```
features/
```
或
```
issues/
```
；spec 文档也不放进
```
easysdd/compound/
```
只认自己的 doc_type——只读写
```
doc_type: learning
```
的文档，不感知
```
compound/
```
目录里其他 doc_type 的文档

Shared guardrails for archival workflows (add-only, quality over quantity, do not write on behalf of users, discoverability, check for duplicates after archiving) can be found in Section 6 of
easysdd/reference/shared-conventions.md
. Rules specific to this skill:

Do not mix with spec — learning documents are not spec documents, do not place them in
```
features/
```
or
```
issues/
```
; spec documents should also not be placed in
```
easysdd/compound/
```
Only recognize own doc_type — only read and write documents with
```
doc_type: learning
```
, do not interact with other doc_type documents in the
```
compound/
```
directory