easysdd-tricks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-tricks

easysdd-tricks 是面向问题的处方性参考库，回答一个问题：**要做 X，经过验证的正确做法是什么？**不需要触发事件，任何时候发现值得沉淀的模式或用法都可以直接写。

典型内容：

某个设计模式在这个项目里的标准写法
某个库 / 框架的核心 API 用法 + 已知坑
某类操作（调试、部署、数据处理……）的命令配方

共享路径与命名约定看
easysdd/reference/shared-conventions.md
。本技能的产物写入
easysdd/compound/
，文件命名
YYYY-MM-DD-trick-{slug}.md
，frontmatter 带
doc_type: trick
。

easysdd-tricks is a problem-oriented prescriptive reference library that answers one question: What is the verified correct way to do X? No trigger event is required; you can directly write whenever you find a pattern or usage worth documenting.

Typical content:

Standard implementation of a design pattern in this project
Core API usage + known pitfalls of a specific library/framework
Command recipes for certain operations (debugging, deployment, data processing...)

See
easysdd/reference/shared-conventions.md
for shared paths and naming conventions. The output of this skill is written to
easysdd/compound/
, with files named
YYYY-MM-DD-trick-{slug}.md
and a frontmatter field
doc_type: trick
.

三种文档类型

Three Document Types

每条技巧文档归属下面三类之一，在 frontmatter 的

type

字段标注：

类型	适用情境	示例
`pattern`	设计模式、架构模式、编程惯用法	"用 Repository 模式隔离数据访问层"、"用 Builder 模式构造复杂配置对象"
`library`	某个库 / 框架的用法、配置方式、常见坑	"Prisma 事务的正确写法"、"Pinia store 的 action 错误处理"
`technique`	具体操作技巧、工具用法、命令配方	"用 jq 从 JSON 里提取嵌套字段"、"git bisect 定位引入 bug 的提交"

类型在查询时各有用途：

查"代码该怎么组织"→
```
pattern
```
查"这个库 / 框架的某个 API 怎么用"→
```
library
```
查"这类操作怎么做"→
```
technique
```

分不清楚就选最接近的，

type

不影响搜索的可用性。

Each trick document belongs to one of the following three categories, marked in the

type

field of the frontmatter:

Type	Applicable Scenarios	Examples
`pattern`	Design patterns, architectural patterns, programming idioms	"Use Repository pattern to isolate data access layer", "Use Builder pattern to construct complex configuration objects"
`library`	Usage, configuration methods, common pitfalls of a specific library/framework	"Correct implementation of Prisma transactions", "Error handling for Pinia store actions"
`technique`	Specific operation skills, tool usage, command recipes	"Extract nested fields from JSON using jq", "Locate bug-introducing commits with git bisect"

Each type serves different purposes during queries:

For questions like "How should I organize my code" →
```
pattern
```
For questions like "How to use a certain API of this library/framework" →
```
library
```
For questions like "How to perform this type of operation" →
```
technique
```

If you're unsure, choose the closest one; the

type

field doesn't affect search usability.

文档格式

Document Format

技巧文档的 frontmatter、正文模板和长示例已拆到同目录

reference.md

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

```
type
```
只允许
```
pattern
```
/
```
library
```
/
```
technique
```
示例优先用项目里的真实代码或命令
```
何时不适用
```
、
```
已知坑
```
、
```
相关文档
```
是可选节，用户说"没什么"就省略

The frontmatter, body template, and long examples of trick documents have been moved to

reference.md

in the same directory. This skill only retains judgment and process rules:

```
type
```
only allows
```
pattern
```
/
```
library
```
/
```
technique
```
Prioritize using real code or commands from the project for examples
Sections like "When not to use", "Known pitfalls", and "Related documents" are optional; omit them if the user says "Nothing"

工作流阶段

Workflow Phases

Phase 1：识别类型（和用户对话）

Phase 1: Identify Type (Dialogue with User)

用最多两个问题确认核心信息：

"这是关于模式 / 结构、某个库 / 框架的用法，还是操作技巧 / 命令？" → 确定
```
type
```
"一句话说：遇到什么情况时会用到它？" → 确定
```
topic
```

用户描述已经够清楚就跳过问题直接进 Phase 1.5。

Confirm core information with at most two questions:

"Is this about patterns/structures, usage of a specific library/framework, or operation skills/commands?" → Determine
```
type
```
"In one sentence: When would this be used?" → Determine
```
topic
```

Skip directly to Phase 1.5 if the user's description is clear enough.

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

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

按

easysdd/reference/shared-conventions.md

§6 第 5 / 6 条执行：

用户话里含"改 / 更新 / 修订 / 补充 / 某条 trick"或明确指向某份旧文档 → 直接走更新已有条目路径，不进新建流程；搜索只是确认定位到哪一条
否则用下面"搜索工具"里的
```
--query
```
查一遍
```
topic
```
，命中语义相近的旧文档时把候选列给用户，让用户选：更新 / supersede / 确实不同主题后再走 Phase 2

更新已有条目的流程：直接读取旧文档 → 和用户对齐要改哪几节 → 跳过 Phase 2 完整代码调查（但被改的节涉及的代码要重读确认未失效） → 起草 diff 给用户 review → 写回原文件，补

updated: YYYY-MM-DD

。

Execute according to Section 6, Items 5/6 of

easysdd/reference/shared-conventions.md

If the user's words include "modify/update/revise/supplement/a certain trick" or explicitly point to an old document → Follow the update existing entry path directly, do not enter the creation process; search only to confirm which entry to locate
Otherwise, use the
```
--query
```
parameter in the "Search Tools" below to search for the
```
topic
```
. If semantically similar old documents are found, present the candidates to the user and let them choose: update / supersede / confirm it's a different topic before proceeding to Phase 2

Process for updating existing entries: Directly read the old document → Align with the user on which sections to modify → Skip the complete code investigation in Phase 2 (but re-read the code related to the modified sections to confirm it hasn't become invalid) → Draft a diff for user review → Write back to the original file and add

updated: YYYY-MM-DD

Phase 2：代码调查（必做，不可跳过）

Phase 2: Code Investigation (Mandatory, Cannot Be Skipped)

技巧是通过代码体现的——用户不贴代码不等于不需要看代码。AI 必须主动调查代码仓，找到技巧的实际落点。

为什么必做？没看代码就写出的"技巧"会停留在抽象层面，下次有人按这条技巧找代码会找不到对应的真实例子，反而失去信心。

根据 topic 和 type 搜索代码仓：
- Grep 关键词（函数名、类名、库导入、模式特征）
- 搜索相关文件（按文件名、目录结构、import 路径）
- 必要时用语义搜索补充
读取关键文件：
- 找到技巧实际使用或实现的代码位置，读取上下文
- ```
library
```
  类：找到库的 import 语句和调用处
- ```
pattern
```
  类：找到模式的结构性代码（接口定义、类继承、组合关系）
- ```
technique
```
  类：找到操作步骤对应的脚本或配置
产出：
- 记下找到的文件路径和关键代码片段，作为后续起草的事实基础
- 代码仓里完全找不到相关代码（纯经验性技巧、外部工具用法）就在 Phase 3 起草时说明"本技巧暂无项目内代码实例"

补充几条情况处理：

用户附带了文件 → 仍然要搜一遍代码仓，确认有没有其他使用点或关联代码
搜索结果为空 → 可以继续（有些技巧确实是"将来要用"的），但必须在文档里注明
找到的代码和用户描述矛盾 → 主动跟用户确认，别闷头写

Techniques are embodied through code — the fact that users don't attach code doesn't mean you don't need to look at code. AI must actively investigate the code repository to find the actual implementation of the technique.

Why is this mandatory? "Techniques" written without checking code will remain at an abstract level. Next time someone looks for code according to this technique, they won't find corresponding real examples, which will instead undermine their confidence.

Search the code repository based on topic and type:
- Grep for keywords (function names, class names, library imports, pattern features)
- Search related files (by file name, directory structure, import path)
- Use semantic search for supplement if necessary
Read key files:
- Locate the code position where the technique is actually used or implemented, and read the context
- For
```
library
```
  type: Find the library's import statements and call sites
- For
```
pattern
```
  type: Find structural code of the pattern (interface definitions, class inheritance, composition relationships)
- For
```
technique
```
  type: Find scripts or configurations corresponding to the operation steps
Output:
- Record the found file paths and key code snippets as the factual basis for subsequent drafting
- If no relevant code is found in the code repository (pure experiential techniques, external tool usages), state "No in-project code examples available for this technique" during Phase 3 drafting

Additional case handling:

If the user attaches files → Still search the code repository to confirm if there are other usage points or related code
If search results are empty → You can proceed (some techniques are indeed "for future use"), but must note this in the document
If the found code contradicts the user's description → Proactively confirm with the user, don't proceed blindly

Phase 3：提炼要点（一次一个问题）

Phase 3: Refine Key Points (One Question at a Time)

按下面顺序问，用户可以随时说"没什么"跳过。结合 Phase 2 找到的代码来提问和补充——不要问用户已经能在代码里看到的东西：

"标准做法是什么？"（或"核心 API / 步骤是什么？"）——代码调查已经看到实现的，直接展示理解请用户确认
"为什么这样做有效？有什么原理吗？"
"有什么反例——什么情况下不该用它？"（可选）
"有没有踩过坑，或者有什么要注意的？"（可选，library 类重点问）
"有代码片段或命令示例吗？"（Phase 2 已找到实际代码就跳过此问，直接用真实代码作为示例基础）

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

Ask in the following order; the user can say "Nothing" to skip at any time. Combine the code found in Phase 2 to ask questions and supplement — don't ask about things the user can already see in the code:

"What is the standard practice?" (or "What is the core API / steps?") → If the implementation is already found through code investigation, directly present your understanding for user confirmation
"Why does this work? Is there any underlying principle?"
"Are there any counterexamples — when shouldn't this be used?" (Optional)
"Have you encountered any pitfalls or things to note?" (Optional, focus on this for
```
library
```
type)
"Are there any code snippets or command examples?" (Skip this question if actual code was found in Phase 2, directly use the real code as the basis for examples)

If the user says "Nothing" or "Skip" to a question, skip it. It's better to omit sections than fill them with empty words.

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

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

AI 根据对话 + Phase 2 代码调查结果起草完整文档（含 YAML frontmatter + 所有正文节）
示例代码优先用 Phase 2 找到的真实项目代码（可精简），别凭空编写
一次性展示给用户 review，别逐节展示逐节问
用户确认后写入文件；有修改就按用户意见调整再写

AI drafts the complete document (including YAML frontmatter + all body sections) based on the dialogue + code investigation results from Phase 2
Prioritize using real project code found in Phase 2 for example code (can be simplified), don't write code out of thin air
Present the complete draft to the user for review at once, don't show section by section and ask for confirmation
Write to the file after user confirmation; adjust according to user's feedback if there are modifications

Phase 5：归档

Phase 5: Archive

新建路径：文件写入

easysdd/compound/

，命名

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

，frontmatter 顶部带

doc_type: trick

（见

reference.md

）

更新路径：写回 Phase 1.5 定位到的原文件，frontmatter 补
```
updated: YYYY-MM-DD
```
supersede 路径：按
```
shared-conventions.md
```
§6 第 5 条处理新旧两份文件
写完后报告完整文件路径

Creation path: Write the file to
```
easysdd/compound/
```
, name it
```
YYYY-MM-DD-trick-{slug}.md
```
, and add
```
doc_type: trick
```
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 files according to Section 6, Item 5 of
```
shared-conventions.md
```
Report the complete file path after writing

Phase 6：可发现性检查

Phase 6: Discoverability Check

写完后检查

AGENTS.md

或

CLAUDE.md

里是否有指引 AI 查阅

easysdd/compound/

沉淀目录的说明。没有就提示用户是否要加一行——别自作主张改文件，只提示，由用户决定。

After writing, check if there are instructions in

AGENTS.md

CLAUDE.md

guiding AI to access the

easysdd/compound/

archive directory. If not, prompt the user whether to add a line — don't modify the file without permission, only prompt and let the user decide.

搜索工具

Search Tools

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

bash

undefined

See
easysdd/reference/tools.md
for complete syntax and examples. This section only lists typical queries specific to tricks.

bash

undefined

按类型 + 框架筛选

Filter by type + framework

python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter type=library --filter framework~={库名}

python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter type=library --filter framework~={library-name}

按技术栈浏览

Browse by tech stack

python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter language=typescript --filter status=active

归档后查重叠

Check for duplicates after archiving

python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --query "{关键词}" --json

---

python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --query "{keywords}" --json

---

守护规则

Guard Rules

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

只归档已验证的做法——"也许应该这样做"不归档；文档内容必须是用户或 AI 确认过有效的
必须调查代码仓——用户没贴代码不等于不需要看，Phase 2 代码调查不可跳过。示例代码优先用项目真实代码，不凭空编写
不替用户写原理——用户说不清楚"为什么有效"的写"原理待补充"，不要 AI 编造听起来合理的解释
示例优先于描述——能用代码说清楚的就用代码，不要只有文字描述
只认自己的 doc_type——只读写
```
doc_type: trick
```
的文档，不感知
```
compound/
```
目录里其他
```
doc_type
```
的文档

Shared guard rules for archiving workflows (add-only, quality over quantity, don't write for users, discoverability, check duplicates after archiving) are in Section 6 of
easysdd/reference/shared-conventions.md
. Rules specific to this skill or refined rules:

Only archive verified practices — "Maybe this should be done" is not archived; document content must be confirmed effective by users or AI
Must investigate the code repository — The fact that users don't attach code doesn't mean you don't need to look at it; Phase 2 code investigation cannot be skipped. Prioritize using real project code for examples, don't write code out of thin air
Don't write principles for users — If the user can't explain "why it works", write "Principle to be supplemented", don't make up plausible explanations with AI
Examples take precedence over descriptions — Use code to explain things whenever possible, don't rely solely on text descriptions
Only recognize its own doc_type — Only read documents with
```
doc_type: trick
```
, don't perceive other
```
doc_type
```
documents in the
```
compound/
```
directory