easysdd-onboarding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-onboarding

把一个仓库接入 easysdd 工作流体系——无论它是一张白纸，还是已经有零散文档的仓库。本技能只做两件事：搭骨架、归旧档。骨架搭好之后各子工作流（feature / issue / compound 等）即可直接在其上运行，不再需要解释目录在哪里。

Onboard a repository into the easysdd workflow system—whether it's a blank slate or a repository with scattered documents. This skill only does two things: Build the skeleton and Organize existing documents. After the skeleton is built, all sub-workflows (feature / issue / compound, etc.) can run directly on it without needing to explain where the directories are.

两条路径

Two Paths

路径	适用情况	产出
空仓库路径	仓库内无任何 spec 类文档，也没有 `easysdd/` 目录	完整的 `easysdd/` 目录骨架 + 必要的骨架文件
迁移路径	仓库内已有零散文档、 `docs/` 目录、架构文档、设计稿，或部分 `easysdd/` 结构	审计报告 + 迁移映射方案（用户逐一确认）+ 落盘

启动后先做一次扫描自动判断，不要让用户自己选——TA 大概率不知道项目里现在有哪些文档。扫描结果模糊（比如只有一个 README）就明说判断依据并问用户确认。

Path	Applicable Scenario	Output
Empty Repository Path	No spec-like documents in the repository, and no `easysdd/` directory	Complete `easysdd/` directory skeleton + necessary skeleton files
Migration Path	The repository already has scattered documents, `docs/` directory, architecture documents, design drafts, or partial `easysdd/` structure	Audit report + migration mapping plan (confirmed by the user one by one) + implementation

After starting, first perform a scan for automatic judgment, don't let the user choose themselves—they probably don't know what documents are currently in the project. If the scan result is ambiguous (such as only having a README), clearly state the judgment basis and ask the user for confirmation.

涉及的路径

Involved Paths

onboarding 完成后，共享路径与命名约定的权威版本是项目里的
easysdd/reference/shared-conventions.md
——由本技能从技能包里复制过去。下面只列 onboarding 需要创建或检查的骨架文件。

After onboarding is completed, the authoritative version of shared paths and naming conventions is
easysdd/reference/shared-conventions.md
in the project—copied from the skill package by this skill. Only the skeleton files that need to be created or checked during onboarding are listed below.

标准骨架（目标状态）

Standard Skeleton (Target State)

onboarding 完成后仓库里应该存在以下骨架：

easysdd/
├── architecture/
│   └── DESIGN.md               ← 架构总入口骨架（首次创建时为占位模板）
├── features/                   ← feature 聚合根（空目录，.gitkeep）
├── issues/                     ← issue 聚合根（空目录，.gitkeep）
├── compound/                   ← 沉淀类统一目录（空目录，.gitkeep）：learning / trick / decision / explore 四种文档按 doc_type + 文件名中间的类型段（YYYY-MM-DD-{doc_type}-{slug}.md）区分
├── tools/                      ← 跨工作流共享的脚本工具（由 onboarding 从技能包释放）
│   ├── search-yaml.py          ← 通用 YAML frontmatter 搜索工具
│   └── validate-yaml.py        ← YAML 语法校验工具
└── reference/                  ← 跨子技能共享的参考文档（由 onboarding 从技能包释放）
    ├── shared-conventions.md   ← 共享元数据口径、checklist 生命周期、阶段收尾推荐
    ├── tools.md                ← 共享脚本用法参考
    └── maintainer-notes.md     ← 断点恢复、扩展点、维护规则

AGENTS.md

在项目根目录，不在
easysdd/
里。onboarding 会检查它存不存在，不存在时提醒用户但不代替用户写——AGENTS.md 的内容高度项目相关，必须由人来填。缺少

AGENTS.md

不阻塞 onboarding 完成，但后续 feature / issue / acceptance 阶段启动前用户需要补齐它，或明确接受当前仓库暂时没有项目级硬约束入口。

After onboarding is completed, the following skeleton should exist in the repository:

easysdd/
├── architecture/
│   └── DESIGN.md               ← Architecture entry skeleton (placeholder template when first created)
├── features/                   ← Feature aggregation root (empty directory, .gitkeep)
├── issues/                     ← Issue aggregation root (empty directory, .gitkeep)
├── compound/                   ← Unified directory for knowledge accumulation (empty directory, .gitkeep): four types of documents (learning / trick / decision / explore) are distinguished by doc_type + the type segment in the middle of the file name (YYYY-MM-DD-{doc_type}-{slug}.md)
├── tools/                      ← Cross-workflow shared script tools (released from the skill package during onboarding)
│   ├── search-yaml.py          ← General YAML frontmatter search tool
│   └── validate-yaml.py        ← YAML syntax validation tool
└── reference/                  ← Reference documents shared across sub-skills (released from the skill package during onboarding)
    ├── shared-conventions.md   ← Shared metadata specifications, checklist lifecycle, recommended phase wrap-up
    ├── tools.md                ← Shared script usage reference
    └── maintainer-notes.md     ← Breakpoint recovery, extension points, maintenance rules

AGENTS.md

is in the project root directory, not in
easysdd/
. Onboarding will check if it exists; if not, it will remind the user but will not write it on behalf of the user—the content of AGENTS.md is highly project-specific and must be filled in by humans. The absence of

AGENTS.md

does not block the completion of onboarding, but users need to complete it before starting the subsequent feature / issue / acceptance phases, or explicitly accept that the current warehouse temporarily has no project-level hard constraint entry.

启动检查

Startup Checks

启动时做下面这些扫描，先扫再说话，不要空口问问题：

检查
easysdd/
目录是否存在
- 不存在：空仓库路径候选
- 存在但不完整：迁移路径（部分补齐）
Glob 全仓库的
.md
文件（排除
```
node_modules/
```
、
```
.git/
```
），重点看：
- 根目录下的
```
DESIGN.md
```
  、
```
ARCHITECTURE.md
```
  、
```
SPEC.md
```
  、
```
README.md
```
- ```
docs/
```
  、
```
doc/
```
  、
```
design/
```
  、
```
spec/
```
  、
```
wiki/
```
  等目录下的文件
- 现有
```
easysdd/
```
  下已有哪些文件
检查
AGENTS.md
是否存在（根目录）
汇报扫描结论——一段话说清楚：
- 找到了哪些可能和 easysdd 体系相关的文档（列文件路径）
- 判断走哪条路径，以及判断依据
- 有哪些不确定项需要用户确认

Perform the following scans when starting, scan first then speak, don't ask questions blindly:

Check if the
easysdd/
directory exists
- Does not exist: Candidate for empty repository path
- Exists but incomplete: Migration path (partial completion)
Glob all
.md
files in the repository (exclude
```
node_modules/
```
,
```
.git/
```
), focus on:
- ```
DESIGN.md
```
  ,
```
ARCHITECTURE.md
```
  ,
```
SPEC.md
```
  ,
```
README.md
```
  in the root directory
- Files in directories such as
```
docs/
```
  ,
```
doc/
```
  ,
```
design/
```
  ,
```
spec/
```
  ,
```
wiki/
```
- Which files already exist under the existing
```
easysdd/
```
Check if
AGENTS.md
exists (root directory)
Report scan conclusions—explain in one paragraph:
- Which documents possibly related to the easysdd system were found (list file paths)
- Which path is judged to be taken, and the judgment basis
- Which uncertain items need user confirmation

空仓库路径

Empty Repository Path

适用条件

Applicable Conditions

仓库内没有任何 spec 类文档（或只有
```
README.md
```
）
```
easysdd/
```
目录不存在

No spec-like documents in the repository (or only
```
README.md
```
)
```
easysdd/
```
directory does not exist

执行步骤

Execution Steps

步骤 1：和用户确认范围

说明即将创建的内容（见上面"标准骨架"），问用户：

项目名 / 简介（用于填入
```
DESIGN.md
```
占位模板）
```
AGENTS.md
```
是否已有，没有的话是否现在就填——想现在填就引导他填关键字段；想之后再填就提醒他 feature/issue 工作流启动时会读它

步骤 2：创建目录骨架

按下面顺序执行，每步完成后继续，不等用户逐步确认——骨架是整体一次性的，逐步确认反而打断节奏：

easysdd/architecture/DESIGN.md

（填入占位模板，见同目录

reference.md

）

```
easysdd/features/.gitkeep
```
```
easysdd/issues/.gitkeep
```
```
easysdd/compound/.gitkeep
```
```
easysdd/tools/
```
（把本技能包
```
easysdd-onboarding/tools/
```
下的所有文件原样复制过去，不修改内容）
```
easysdd/reference/
```
（把本技能包
```
easysdd-onboarding/reference/
```
下的所有文件原样复制过去，不修改内容——这是所有 easysdd 子技能在运行时共享参考文档的唯一方式）

步骤 3：AGENTS.md 提醒

如果根目录没有

AGENTS.md

：

AGENTS.md
还不存在。它是 easysdd 所有子工作流的"项目硬约束入口"——记录代码规范、已知坑、禁止事项。建议现在创建一个最小版本。你想现在填，还是之后自己创建？

用户选"现在填"：提供最小模板（见同目录

reference.md

），引导用户填写关键字段后保存。用户选"之后"：记录在汇报里，告诉用户"下次触发 feature/issue 工作流前记得补上"。

步骤 4：验收汇报

列出建了哪些文件，告诉用户：

easysdd 骨架已就绪。现在可以：
开始一个新功能：触发
easysdd-feature
技能
报告一个问题：触发
easysdd-issue
技能
沉淀知识：触发
easysdd-learning
技能

Step 1: Confirm scope with the user

Explain the content to be created (see "Standard Skeleton" above), ask the user:

Project name / introduction (used to fill in the
```
DESIGN.md
```
placeholder template)
Whether
```
AGENTS.md
```
already exists; if not, whether to fill it in now—if they want to fill it in now, guide them to fill in the key fields; if they want to do it later, remind them that it will be read when the feature/issue workflow starts

Step 2: Create directory skeleton

Execute in the following order, proceed after each step is completed, do not wait for user step-by-step confirmation—the skeleton is a one-time whole, step-by-step confirmation will disrupt the rhythm:

```
easysdd/architecture/DESIGN.md
```
(fill in the placeholder template, see
```
reference.md
```
in the same directory)
```
easysdd/features/.gitkeep
```
```
easysdd/issues/.gitkeep
```
```
easysdd/compound/.gitkeep
```
```
easysdd/tools/
```
(copy all files under
```
easysdd-onboarding/tools/
```
in this skill package as-is, without modifying the content)
```
easysdd/reference/
```
(copy all files under
```
easysdd-onboarding/reference/
```
in this skill package as-is, without modifying the content—this is the only way all easysdd sub-skills share reference documents during runtime)

Step 3: AGENTS.md Reminder

If there is no

AGENTS.md

in the root directory:

AGENTS.md
does not exist yet. It is the "project hard constraint entry" for all easysdd sub-workflows—recording code specifications, known pitfalls, and prohibited items. It is recommended to create a minimal version now. Do you want to fill it in now, or create it yourself later?

If the user selects "Fill in now": Provide a minimal template (see

reference.md

in the same directory), guide the user to fill in the key fields and save. If the user selects "Later": Record it in the report and tell the user "Remember to fill it in before triggering the feature/issue workflow next time".

Step 4: Acceptance Report

List which files were created, tell the user:

The easysdd skeleton is ready. Now you can:
Start a new feature: Trigger the
easysdd-feature
skill
Report an issue: Trigger the
easysdd-issue
skill
Accumulate knowledge: Trigger the
easysdd-learning
skill

迁移路径

Migration Path

适用条件

Applicable Conditions

仓库内有零散的 spec 类文档、设计文档、或部分

easysdd/

结构。

The repository has scattered spec-like documents, design documents, or partial

easysdd/

structure.

执行步骤

Execution Steps

步骤 1：生成审计报告

把扫描结果整理成一张映射表，展示给用户：

现有文件	推测内容类型	建议归入 easysdd 位置	置信度
`docs/DESIGN.md`	项目架构文档	`easysdd/architecture/DESIGN.md`	高
`docs/feature-auth.md`	某功能的设计稿	`easysdd/features/YYYY-MM-DD-auth/auth-design.md`	中
`SPEC.md`	功能需求文档？	需用户确认	低
...	...	...	...

置信度的含义：

高：文件内容和目标位置语义明确匹配（比如架构文档放架构目录）
中：可以推断但有歧义（比如一份文档把需求、设计和验收混写在一起）
低：文件内容不明确，或映射到多个位置都合理

步骤 2：逐条和用户对齐

对每一条置信度"中"或"低"的映射，用

AskUserQuestion

问用户确认：

中置信度：给出推断理由，问"是否按这个方式归位？"
低置信度：描述文件内容，给 2-3 个候选位置让用户单选，并提供"跳过（不迁移）"选项

高置信度的映射不需要逐条问，但要在汇报里列出来，让用户有机会反对。理由是高置信度的判断也可能错，但逐条问会让节奏失控——汇报里列出来等于给了用户一次复审机会但不打断流程。

步骤 3：处理"中途写了一半"的 easysdd 文档

如果

easysdd/

已部分存在：

检查已有目录是否符合命名规范（
```
YYYY-MM-DD-{slug}
```
格式）
检查已有文件是否有内容（空文件 vs 有内容）
不符合规范但有内容的文件：提示用户，问是否重命名
空占位文件（
```
.gitkeep
```
或空
```
.md
```
）：直接补齐，不用问用户

步骤 4：补齐缺失的骨架

对照上面的标准骨架，把用户确认迁移方案后仍然缺失的目录和文件补齐。已有内容的目录不要覆盖，只补空缺。

easysdd/tools/

下缺失的工具文件从本技能包的

easysdd-onboarding/tools/

对应补齐；已存在的文件不覆盖（用户可能已经改过）。

easysdd/reference/

下缺失的参考文档从本技能包的

easysdd-onboarding/reference/

对应补齐；已存在的文件不覆盖（用户可能已经改过）。如果项目里已有同名文件但内容和技能包里不同，提示用户一次（"项目里这份和当前技能包不一致，需要我列出差异吗？"），但不替他们覆盖——reference 是被所有子技能读的共享口径，覆盖成本高。

步骤 5：处理不迁移的文件

用户选择"跳过"的文件：不移动、不删除、不重命名，在汇报里标注"保留原位（未纳入 easysdd 体系）"。绝对不允许未经确认就移动或删除任何已有文件——理由很简单：onboarding 的入口只允许 AI 整理而不允许 AI 替用户做删除决定，删错了恢复成本极高。

步骤 6：AGENTS.md 提醒（同空仓库路径步骤 3）

步骤 7：验收汇报

列出：

迁移的文件清单（from → to）
新创建的骨架文件清单
未迁移的文件清单（保留原位）
下一步建议

Step 1: Generate Audit Report

Organize the scan results into a mapping table and display it to the user:

Existing File	Inferred Content Type	Suggested easysdd Location	Confidence
`docs/DESIGN.md`	Project architecture document	`easysdd/architecture/DESIGN.md`	High
`docs/feature-auth.md`	Design draft of a certain feature	`easysdd/features/YYYY-MM-DD-auth/auth-design.md`	Medium
`SPEC.md`	Functional requirement document?	Need user confirmation	Low
...	...	...	...

Meaning of Confidence:

High: The file content clearly matches the target location semantically (e.g., architecture documents are placed in the architecture directory)
Medium: Can be inferred but has ambiguity (e.g., a document mixes requirements, design, and acceptance together)
Low: The file content is unclear, or it is reasonable to map to multiple locations

Step 2: Align with the user item by item

For each mapping with "Medium" or "Low" confidence, use

AskUserQuestion

to ask the user for confirmation:

Medium confidence: Provide the inference reason and ask "Should it be placed in this way?"
Low confidence: Describe the file content, provide 2-3 candidate locations for the user to select, and provide a "Skip (do not migrate)" option

Mappings with high confidence do not need to be asked item by item, but should be listed in the report so that the user has the opportunity to object. The reason is that high-confidence judgments may also be wrong, but asking item by item will disrupt the rhythm—listing them in the report gives the user a review opportunity without interrupting the process.

Step 3: Handle easysdd documents "half-written in the middle"

easysdd/

already partially exists:

Check if the existing directories comply with the naming convention (
```
YYYY-MM-DD-{slug}
```
format)
Check if the existing files have content (empty files vs. files with content)
Files that do not comply with the convention but have content: Prompt the user and ask whether to rename them
Empty placeholder files (
```
.gitkeep
```
or empty
```
.md
```
): Directly complete them without asking the user

Step 4: Complete the missing skeleton

Compare with the standard skeleton above, complete the directories and files that are still missing after the user confirms the migration plan. Do not overwrite directories with existing content, only fill in the gaps.

Missing tool files under

easysdd/tools/

are completed from the corresponding

easysdd-onboarding/tools/

in this skill package; existing files are not overwritten (users may have modified them).

Missing reference documents under

easysdd/reference/

are completed from the corresponding

easysdd-onboarding/reference/

in this skill package; existing files are not overwritten (users may have modified them). If there is a file with the same name in the project but the content is different from that in the skill package, prompt the user once ("This file in the project is inconsistent with the current skill package, do you need me to list the differences?"), but do not overwrite it for them—reference is a shared specification read by all sub-skills, and the cost of overwriting is high.

Step 5: Handle files that are not migrated

Files that the user chooses to "Skip": Do not move, delete, or rename them, mark "Keep in original location (not included in the easysdd system)" in the report. It is absolutely not allowed to move or delete any existing files without confirmation—the reason is simple: the onboarding entry only allows AI to organize, not to make deletion decisions on behalf of the user, and the recovery cost is extremely high if deleted by mistake.

Step 6: AGENTS.md Reminder (same as Step 3 of the Empty Repository Path)

Step 7: Acceptance Report

List:

List of migrated files (from → to)
List of newly created skeleton files
List of non-migrated files (kept in original location)
Next-step suggestions

骨架文件模板

Skeleton File Templates

DESIGN.md

占位模板和

AGENTS.md

最小模板已拆到同目录

reference.md

。本技能正文只保留流程，不再内嵌长模板。

The

DESIGN.md

placeholder template and the minimal

AGENTS.md

template have been split into

reference.md

in the same directory. This skill only retains the process in the main text and no longer embeds long templates.

退出条件

Exit Conditions

```
easysdd/
```
目录骨架完整（六个子目录都存在：
```
architecture/
```
、
```
features/
```
、
```
issues/
```
、
```
compound/
```
、
```
tools/
```
、
```
reference/
```
）
```
easysdd/tools/
```
和
```
easysdd/reference/
```
下的共享脚本和参考文档已从本技能包复制过去（子技能在运行时必须能读到这些文件）
```
easysdd/architecture/DESIGN.md
```
已建（哪怕是占位内容）
迁移路径：每一条映射都有明确处理结果（迁移 / 保留原位）
迁移路径：没有未经用户确认就移动的文件
```
AGENTS.md
```
状态已明确（存在 / 用户知道需要补）
验收汇报已给出，用户知道下一步该触发哪个子技能

The
```
easysdd/
```
directory skeleton is complete (all six sub-directories exist:
```
architecture/
```
,
```
features/
```
,
```
issues/
```
,
```
compound/
```
,
```
tools/
```
,
```
reference/
```
)
Shared scripts and reference documents under
```
easysdd/tools/
```
and
```
easysdd/reference/
```
have been copied from this skill package (sub-skills must be able to read these files during runtime)
```
easysdd/architecture/DESIGN.md
```
has been created (even if it's placeholder content)
Migration path: Each mapping has a clear processing result (migrated / kept in original location)
Migration path: No files were moved without user confirmation
The status of
```
AGENTS.md
```
is clear (exists / user knows it needs to be completed)
The acceptance report has been provided, and the user knows which sub-skill to trigger next

容易踩的坑

Common Pitfalls

未经用户确认就移动或删除已有文件——迁移路径的核心原则是用户拍板，不是 AI 自作主张
替用户填写 AGENTS.md 的实质内容——AGENTS.md 里的规范和禁忌必须项目 owner 来定，AI 只提供模板和引导
建完骨架后立刻开始某个 feature/issue——onboarding 的职责是"搭环境"，不是"开始干活"，做完骨架就结束
把 AGENTS.md 建到
easysdd/
里——AGENTS.md 是根目录文件，不属于
```
easysdd/
```
下
把低置信度的映射也直接执行——置信度低 = 必须问，不问直接迁是在替用户做判断
遇到部分存在的
easysdd/
结构就全部覆盖重建——有内容的文件不允许覆盖，只补空缺
Glob 时忘记排除
node_modules/
、
.git/
——这会让扫描结果充斥噪声，判断路径会出错

Moving or deleting existing files without user confirmation—the core principle of the migration path is that the user makes the final decision, not the AI acting on its own
Filling in the substantive content of AGENTS.md on behalf of the user—the specifications and taboos in AGENTS.md must be determined by the project owner, the AI only provides templates and guidance
Starting a feature/issue immediately after building the skeleton—the responsibility of onboarding is to "set up the environment", not to "start working", it ends after the skeleton is completed
Creating AGENTS.md in
easysdd/
—AGENTS.md is a root directory file and does not belong under
```
easysdd/
```
Directly executing mappings with low confidence—low confidence = must ask, migrating without asking is making judgments on behalf of the user
Reconstructing all existing partial
easysdd/
structures by overwriting—files with content are not allowed to be overwritten, only gaps are filled
Forgetting to exclude
node_modules/
and
.git/
when globbing—this will fill the scan results with noise and lead to wrong path judgments

easysdd-onboarding

Original

Translation

easysdd-onboarding

easysdd-onboarding

两条路径

Two Paths

涉及的路径

Involved Paths

标准骨架（目标状态）

Standard Skeleton (Target State)

启动检查

Startup Checks

空仓库路径

Empty Repository Path

适用条件

Applicable Conditions

执行步骤

Execution Steps

迁移路径

Migration Path

适用条件

Applicable Conditions

执行步骤

Execution Steps

骨架文件模板

Skeleton File Templates

退出条件

Exit Conditions

容易踩的坑

Common Pitfalls

相关文档

Related Documents