onboard-codebase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: onboard-codebase

WHAT

内容

Purpose và context

目的与上下文

Purpose: Analyze unmapped codebase, extract technical/business context, populate Wiki per project standards.
Trigger (when to use):
- Installing agentic setup into legacy/existing project.
- Wiki outdated or has context gap from recent code changes.
Non-goals: không sửa code dự án, không ghi đè trang wiki viết tay khi chưa kiểm
```
## Origin
```
, không lấy README/comment làm sự thật thay cho code.

目的： 分析尚未映射的代码库，提取技术/业务上下文，并按照项目标准填充 Wiki。
触发条件（何时使用）：
- 在遗留/现有项目中安装 Agent 配置。
- Wiki 已过时，或近期代码变更造成上下文缺口。
非目标： 不修改项目代码；未检查
```
## Origin
```
前，不覆盖手写 Wiki 页面；不把 README/注释当作代码的事实依据。

Mental model

思维模型

codebase → infrastructure audit → domain logic + patterns → (frontend style nếu có) → business rules → entities → wiki (entities · concepts · fe-style · AGENT-business.md) → index + log → lint

代码库 → 基础设施审计 → 领域逻辑 + 设计模式 →（如果有 frontend）→ 业务规则 → 实体 → wiki（entities · concepts · fe-style · AGENT-business.md）→ index + log → lint

。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	codebase dự án	có	đọc implementation để kiểm chứng mọi claim
Out	`llmwiki/wiki/entities/project-structure.md`	có	cấu trúc thư mục, stack, entry point, build/deploy
Out	`llmwiki/wiki/concepts/*.md`	có	concept domain + pattern
Out	`llmwiki/wiki/concepts/fe-style.md`	khi có frontend	giá trị thật (hex, px/rem, class)
Out	`AGENT-business.md`	có	user stories + business rules suy ngược từ code
Out	`llmwiki/wiki/entities/*` + index + log	có	services, external API, bảng DB
Out	draft output report	có	mục Delivery

	字段	必需？	含义
In	项目代码库	是	读取实现代码，以核验所有结论
Out	`llmwiki/wiki/entities/project-structure.md`	是	目录结构、技术栈、入口点、构建/部署
Out	`llmwiki/wiki/concepts/*.md`	是	领域概念 + 设计模式
Out	`llmwiki/wiki/concepts/fe-style.md`	存在 frontend 时	实际值（hex、px/rem、class）
Out	`AGENT-business.md`	是	从代码逆向推导的用户故事 + 业务规则
Out	`llmwiki/wiki/entities/*` + index + log	是	services、external API、数据库表
Out	草稿形式的输出报告	是	交付部分

Rules và capabilities

规则与能力

RULE-01 (MUST): ALWAYS read implementation to verify business claims.
RULE-02 (MUST): Cross-reference
```
README.md
```
/comments but prioritize truth in code.
RULE-03 (MUST): Focus on "Why" and "How" at code level, not just "What".
RULE-04 (MUST): NEVER overwrite existing manual wiki entries without checking
```
## Origin
```
section.
RULE-05 (MUST): OKF v0.1 (R9): mọi trang wiki bắt đầu bằng YAML frontmatter (
```
---
```
) có
```
type
```
không rỗng (
```
concept
```
/
```
entity
```
/
```
source
```
) — copy
```
_template.md
```
tương ứng. Giữ
```
## Origin
```
(R2).
RULE-06 (MUST): For
```
fe-style.md
```
: record actual values (hex codes, px/rem sizes, class names), not descriptions — goal is reproducible visual style without guessing.
Capabilities: đọc toàn bộ codebase; ghi
```
llmwiki/wiki/
```
+
```
AGENT-business.md
```
; chạy lint wiki.

RULE-01 (MUST)：始终阅读实现代码，以核验所有业务结论。
RULE-02 (MUST)：交叉参考
```
README.md
```
/注释，但始终以代码中的事实为准。
RULE-03 (MUST)：聚焦代码层面的“为什么”和“如何”，而不仅仅是“是什么”。
RULE-04 (MUST)：未检查
```
## Origin
```
部分前，绝不覆盖现有的人工 Wiki 条目。
RULE-05 (MUST)：OKF v0.1 (R9)： 所有 Wiki 页面都必须以 YAML frontmatter (
```
---
```
) 开头，且
```
type
```
不得为空（
```
concept
```
/
```
entity
```
/
```
source
```
）——复制对应的
```
_template.md
```
。保留
```
## Origin
```
(R2)。
RULE-06 (MUST)：对于
```
fe-style.md
```
，记录实际值（hex 色值、px/rem 尺寸、class 名称），而不是文字描述——目标是让视觉风格可复现且无需猜测。
能力：读取整个代码库；写入
```
llmwiki/wiki/
```
+
```
AGENT-business.md
```
；运行 Wiki lint。

Failure boundaries

失败边界

Không có frontend → bỏ bước 3, không tạo
```
fe-style.md
```
(succeeded hẹp).
Trang wiki viết tay đã có mà
```
## Origin
```
không cho phép ghi đè → clarify trước khi sửa.
Claim nghiệp vụ không kiểm được trong code → không ghi như sự thật; ghi rõ chưa xác minh.
```
lint
```
báo mâu thuẫn → sửa trang rồi chạy lại trước khi coi là xong.

没有 frontend → 跳过步骤 3，不创建
```
fe-style.md
```
（范围较窄的成功结果）。
目标 Wiki 页面已存在且为手写内容，但其
```
## Origin
```
不允许覆盖 → 修改前先 clarify。
业务结论无法从代码中核验 → 不得将其写作事实；应明确标注为尚未验证。
```
lint
```
报告矛盾 → 修复相关页面后重新运行，再视为完成。

HOW

执行方式

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	codebase	Infrastructure Audit	`project-structure.md`	—
W02	judgment	code domain	Deep Code Analysis (services, models, patterns)	concepts	—
W03	judgment	frontend	Frontend & Style Audit	`fe-style.md`	không có frontend → skip (B01)
W04	judgment	code	Business Logic Extraction	`AGENT-business.md`	claim không kiểm được → không ghi
W05	judgment	code	Entity Cataloging	entities	—
W06	effect	kết quả W01–W05	Knowledge Injection + index + log	wiki cập nhật	trang tay → kiểm `## Origin`
W07	deterministic	wiki	Final Verification: `lint`	không mâu thuẫn	mâu thuẫn → sửa, lặp W07

Chi tiết từng bước (nguồn chân lý cho W01–W07):

Infrastructure Audit:
- Map directory structure.
- Identify tech stack, entry points, build/deploy scripts.
- Store in
```
llmwiki/wiki/entities/project-structure.md
```
  .
Deep Code Analysis:
- Scan for core domain logic (Services, Models, Controllers).
- Identify patterns (Repository, Event-driven, etc.).
- Extract Concepts for
```
llmwiki/wiki/concepts/
```
  .
Frontend & Style Audit (skip if no frontend):
- Identify UI framework (Next.js, React, Vue, etc.) and CSS approach (Tailwind, CSS Modules, styled-components, SCSS).
- Extract design tokens: color palette, typography scale, spacing, breakpoints — from
```
tailwind.config.*
```
  , CSS variables, or theme files.
- Identify component library (shadcn/ui, MUI, Ant Design, Radix, Headless UI, etc.) and local wrappers.
- Trace global styles:
```
globals.css
```
  , base layout files, font loading strategy.
- Document component naming conventions (PascalCase, feature-folder, colocated stories, etc.).
- Note UI state management (Zustand, Jotai, Context, Redux, etc.) and data-fetching pattern (React Query, SWR, server actions, etc.).
- Capture routing conventions (file-based, nested layouts, auth guards).
- Store in
```
llmwiki/wiki/concepts/fe-style.md
```
  .
Business Logic Extraction:
- Reverse-engineer user stories and business rules from code.
- Generate/Update
```
AGENT-business.md
```
  .
Entity Cataloging:
- List internal services, external APIs, database tables.
- Create entries in
```
llmwiki/wiki/entities/
```
  .
Knowledge Injection:
- Synthesize into Wiki structure.
- Update
```
llmwiki/wiki/index.md
```
  and
```
llmwiki/wiki/log.md
```
  .
Final Verification:
- Run
```
lint
```
  on generated wiki — check for contradictions.

步骤	类型	输入	操作	输出/退出条件	失败/下一步
W01	判断	代码库	基础设施审计	`project-structure.md`	—
W02	判断	领域代码	深度代码分析（Services、Models、Patterns）	concepts	—
W03	判断	frontend	前端与样式审计	`fe-style.md`	没有 frontend → 跳过 (B01)
W04	判断	代码	业务逻辑提取	`AGENT-business.md`	结论无法核验 → 不写入
W05	判断	代码	实体编目	entities	—
W06	执行	W01–W05 的结果	知识注入（Knowledge Injection）+ index + log	Wiki 已更新	人工页面 → 检查 `## Origin`
W07	确定性	Wiki	最终验证： `lint`	无矛盾	存在矛盾 → 修复并重复 W07

各步骤详情（W01–W07 的事实来源）：

基础设施审计：
- 梳理目录结构。
- 识别技术栈、入口点和构建/部署脚本。
- 保存到
```
llmwiki/wiki/entities/project-structure.md
```
  。
深度代码分析：
- 扫描核心领域逻辑（Services、Models、Controllers）。
- 识别设计模式（Repository、Event-driven 等）。
- 为
```
llmwiki/wiki/concepts/
```
  提取概念（Concepts）。
前端与样式审计（没有 frontend 时跳过）：
- 识别 UI 框架（Next.js、React、Vue 等）和 CSS 方案（Tailwind、CSS Modules、styled-components、SCSS）。
- 从
```
tailwind.config.*
```
  、CSS 变量或主题文件中提取设计令牌（design tokens）：色板、字体排版比例、间距、断点。
- 识别组件库（component library，如 shadcn/ui、MUI、Ant Design、Radix、Headless UI 等）和本地封装组件（local wrappers）。
- 追踪全局样式：
```
globals.css
```
  、基础布局文件和字体加载策略。
- 记录组件命名约定（PascalCase、feature-folder、colocated stories 等）。
- 说明 UI 状态管理（Zustand、Jotai、Context、Redux 等）和数据获取模式（React Query、SWR、server actions 等）。
- 梳理路由约定（基于文件、嵌套布局、auth guards）。
- 保存到
```
llmwiki/wiki/concepts/fe-style.md
```
  。
业务逻辑提取：
- 从代码中逆向推导用户故事和业务规则。
- 生成/更新
```
AGENT-business.md
```
  。
实体编目：
- 列出内部 services、external APIs 和数据库表。
- 在
```
llmwiki/wiki/entities/
```
  中创建条目。
知识注入：
- 将结果整合为 Wiki 结构。
- 更新
```
llmwiki/wiki/index.md
```
  和
```
llmwiki/wiki/log.md
```
  。
最终验证：
- 对生成的 Wiki 运行
```
lint
```
  ——检查是否存在矛盾。

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	dự án có frontend	chạy bước 3 Frontend & Style Audit	không có frontend → skip	W04
B02	conditional_required	trang wiki đích đã tồn tại, viết tay	đọc `## Origin` trước; chỉ cập nhật khi không đè nội dung thủ công	không chắc → hỏi user	W06

ID	类型	Guard	行为	跳过/失败	汇合点
B01	条件必需	项目有 frontend	执行步骤 3：前端与样式审计	没有 frontend → 跳过	W04
B02	条件必需	目标 Wiki 页面已存在且为手写内容	先读取 `## Origin` ；仅在不会覆盖人工内容时更新	不确定 → 询问用户	W06

Validation và stopping

验证与停止条件

Tất định:

lint

wiki không còn mâu thuẫn; mọi trang có frontmatter

type

## Origin

(R2/R9). Cần review: claim nghiệp vụ phải truy về code đã đọc. Dừng sau W07 xanh + output report.

确定性完成条件：Wiki 的

lint

不再存在矛盾；每个页面都有 frontmatter

type

## Origin

(R2/R9)。需要人工复核：业务结论必须能追溯到已读代码。W07 通过并生成输出报告后停止。

Examples

示例

Positive: onboard một repo Next.js + Go →
```
project-structure.md
```
(stack, entry, build), concepts domain,
```
fe-style.md
```
ghi
```
#0F172A
```
,
```
text-sm
```
/
```
14px
```
, shadcn/ui,
```
AGENT-business.md
```
, entities bảng DB →
```
lint
```
sạch → draft report.
Boundary/failure: repo chỉ có backend Go → bỏ bước 3, không tạo
```
fe-style.md
```
; README nói "hỗ trợ refund" nhưng code không có handler refund → không ghi vào
```
AGENT-business.md
```
như sự thật.

正向示例： 对一个 Next.js + Go 仓库执行代码库上手 → 生成
```
project-structure.md
```
（技术栈、入口、构建）、领域概念、记录
```
#0F172A
```
、
```
text-sm
```
/
```
14px
```
、shadcn/ui 的
```
fe-style.md
```
、
```
AGENT-business.md
```
、数据库表实体 →
```
lint
```
无问题 → 草稿报告。
边界/失败示例： 只有 Go backend 的仓库 → 跳过步骤 3，不创建
```
fe-style.md
```
；README 声称“支持退款（refund）”，但代码中没有 refund handler → 不把这一点作为事实写入
```
AGENT-business.md
```
。

Delivery — Output Report

交付——输出报告

After all main skill tasks complete, write a propose draft to the wiki.

完成所有主要 Skill 任务后，向 wiki 写入一份待审（proposed）草稿。

Steps

步骤

1. Build the filename:

Format:
```
DDMMYY-<ten>.md
```
```
DDMMYY
```
= today (e.g.,
```
020626
```
for 2 June 2026)

<ten>

= 2–4 kebab-case words summarising what was done (e.g.,

landing-page-coteccons

brand-kit-fintech

ingest-auth-spec

)

2. Write

llmwiki/wiki/sources/draft/DDMMYY-<ten>.md

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

1. 构建文件名：

格式：
```
DDMMYY-<ten>.md
```
```
DDMMYY
```
= 今天（例：
```
020626
```
表示 2026 年 6 月 2 日）
```
<ten>
```
= 2–4 个概括完成内容的 kebab-case 单词（例：
```
landing-page-coteccons
```
、
```
brand-kit-fintech
```
、
```
ingest-auth-spec
```
）

2. 写入

llmwiki/wiki/sources/draft/DDMMYY-<ten>.md

：

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

DDMMYY-<ten>

Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD

What

Output

Files

File	Action
`path/to/file`	created / modified

File	Action
`path/to/file`	created / modified

Notes

Invoked via:
```
/<skill-name>
```
skill

Invoked via:
```
/<skill-name>
```
skill

Origin

Draft:
```
wiki/sources/draft/DDMMYY-<ten>.md
```
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)


**3. Update wiki index & log:**
- `llmwiki/wiki/index.md` — append one row: `| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — append: `## YYYY-MM-DD — <skill-name> — <ten>`

> Skip only when the skill produces zero artefacts and zero decisions (e.g., a pure display mode like `/caveman-stats`).

Draft:
```
wiki/sources/draft/DDMMYY-<ten>.md
```
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)


**3. 更新 Wiki index 与 log：**
- `llmwiki/wiki/index.md`——追加一行：`| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md`——追加：`## YYYY-MM-DD — <skill-name> — <ten>`

> 只有当 Skill 未产出任何工件且未作出任何决策时，才可以跳过（例如 `/caveman-stats` 这类纯展示模式）。