onboard-codebase

技能：onboard-codebase

内容

目的与背景

• 目的： 分析尚未梳理的代码库，提取技术与业务背景，并按照项目标准填充 Wiki。
• 触发条件（何时使用）：
  • 将 Agentic 配置安装到遗留项目或现有项目中。
  • Wiki 已过时，或近期代码变更导致背景信息缺失。
• 非目标： 不修改项目代码；未经检查 ## Origin，不覆盖手写的 Wiki 页面；不以 README 或注释代替代码作为事实来源。

思维模型

代码库 → 基础设施审计 → 领域逻辑 + 模式 →（如有前端，则检查前端样式）→ 业务规则 → 实体 → wiki（实体 · 概念 · 前端样式 · AGENT-business.md）→ 索引 + 日志 → lint。

输入与输出约定

	字段	必填？	含义
输入	项目代码库	是	阅读实现，以验证所有声明
输出	llmwiki/wiki/entities/project-structure.md	是	目录结构、技术栈、入口点、构建/部署
输出	llmwiki/wiki/concepts/*.md	是	领域概念 + 模式
输出	llmwiki/wiki/concepts/fe-style.md	有前端时	实际值（hex、px/rem、class）
输出	AGENT-business.md	是	根据代码反向推导的用户故事 + 业务规则
输出	llmwiki/wiki/entities/* + 索引 + 日志	是	服务、外部 API、数据库表
输出	草稿输出报告	是	Delivery 部分

规则与能力

• 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。

失败边界

• 没有前端 → 跳过步骤 3，不创建 fe-style.md（部分成功）。
• 已有手写 Wiki 页面，且 ## Origin 不允许覆盖 → 修改前先确认。
• 无法在代码中验证的业务声明 → 不得将其记录为事实；明确标注尚未验证。
• lint 报告冲突 → 修复页面并重新运行，然后再视为完成。

操作方式

主要工作流

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	judgment	代码库	基础设施审计	project-structure.md	—
W02	judgment	代码领域	深入代码分析（服务、模型、模式）	概念	—
W03	judgment	前端	前端与样式审计	fe-style.md	没有前端 → 跳过（B01）
W04	judgment	代码	业务逻辑提取	AGENT-business.md	无法验证的声明 → 不记录
W05	judgment	代码	实体编目	实体	—
W06	effect	W01–W05 的结果	知识注入 + 索引 + 日志	Wiki 已更新	手动编写的页面 → 检查 ## Origin
W07	deterministic	Wiki	最终验证：lint	无矛盾	有矛盾 → 修复，重复执行 W07

各步骤详情（W01–W07 的事实依据）：

1. 基础设施审计：
   • 绘制目录结构图。
   • 识别技术栈、入口点、构建/部署脚本。
   • 存储到 llmwiki/wiki/entities/project-structure.md。
2. 深入代码分析：
   • 扫描核心领域逻辑（服务、模型、控制器）。
   • 识别模式（Repository、事件驱动等）。
   • 提取概念并存入 llmwiki/wiki/concepts/。
3. 前端与样式审计（没有前端则跳过）：
   • 识别 UI 框架（Next.js、React、Vue 等）和 CSS 方案（Tailwind、CSS Modules、styled-components、SCSS）。
   • 提取设计令牌：调色板、字体排印比例、间距、断点——从 tailwind.config.*、CSS 变量或主题文件中提取。
   • 识别组件库（shadcn/ui、MUI、Ant Design、Radix、Headless UI 等）及本地封装。
   • 梳理全局样式：globals.css、基础布局文件、字体加载策略。
   • 记录组件命名约定（PascalCase、功能文件夹、同目录 stories 等）。
   • 记录 UI 状态管理方式（Zustand、Jotai、Context、Redux 等）和数据获取模式（React Query、SWR、服务端操作等）。
   • 记录路由约定（基于文件、嵌套布局、身份验证守卫）。
   • 存储到 llmwiki/wiki/concepts/fe-style.md。
4. 业务逻辑提取：
   • 从代码中逆向分析用户故事和业务规则。
   • 生成/更新 AGENT-business.md。
5. 实体编目：
   • 列出内部服务、外部 API、数据库表。
   • 在 llmwiki/wiki/entities/ 中创建条目。
6. 知识注入：
   • 整合并写入 Wiki 结构。
   • 更新 llmwiki/wiki/index.md 和 llmwiki/wiki/log.md。
7. 最终验证：
   • 对生成的 Wiki 运行 lint，检查是否存在矛盾。

分支

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

验证与停止条件

必须满足：lint 检查后 Wiki 中不再有矛盾；所有页面都有 frontmatter type 和 ## Origin（R2/R9）。需要审核：业务声明必须能追溯到已读取的代码。W07 通过且输出报告后停止。

示例

• 正向示例： 接入一个 Next.js + Go 仓库 → project-structure.md（技术栈、入口、构建）、领域概念、记录 #0F172A、text-sm/14px、shadcn/ui 的 fe-style.md、AGENT-business.md、数据库表实体 → lint 检查无误 → 起草报告。
• 边界/失败： 仓库只有 Go 后端 → 跳过步骤 3，不创建 fe-style.md；README 写着“支持退款”，但代码中没有退款处理程序 → 不要将其作为事实写入 AGENT-business.md。

交付 — 输出报告

完成所有主要技能任务后，向 Wiki 写入一份提案草稿。

步骤

1. 构建文件名：

• 格式：DDMMYY-<ten>.md
• DDMMYY = 今天的日期（例如，2026 年 6 月 2 日为 020626）
• <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
<One sentence — what this skill invocation produced or decided>

## Output
<Key artefacts, files created/modified, or decisions made>

## Files
| File | Action |
|------|--------|
| `path/to/file` | created / modified |

## Notes
- 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. 更新 wiki 索引和日志：

• 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>

仅当该技能未生成任何产物且未作出任何决策时才跳过（例如，纯展示模式 /caveman-stats）。