init

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# /cc-code:init — 项目场域初始化 / 版本升级

执行 cc-code 工作流的入场协议。**同时负责把旧版场域升级到当前插件规范。**

## 第 1 步：三轨判定

扫描当前工作区，由 `.cc_code/.cc_code_version` 版本戳分流：

| 探测条件 | 轨道 | 行为 |
| --- | --- | --- |
| 无 `active/Agent.md`，且存在 `src/` / `package.json` / `go.mod` 等旧代码或根目录已有 `CLAUDE.md` | **Track A** 旧项目接管 | 扫描技术栈+断层，与用户多轮补 PRD；执行第 2A 步：主控原文分拣旧 `CLAUDE.md`，再按顺序派各文件写者落盘 |
| 无 `active/Agent.md`，全空目录 | **Track B** 新项目 | 直接搭场域 + 盖版本戳，等待需求（规划时由主控派 pm agent，init 不扮演角色） |
| 有 `active/Agent.md`，且版本戳 **==** 插件版本 | **Track C** 已最新 | 跳过脚手架，搬散落物 + ⭐**跑 D4 骨架格式体检**（0.9.0 起），再进第 3 步 |
| 有 `active/Agent.md`，但版本戳**缺失或更旧** | **Track D** ⭐升级迁移 | 脚本做 D1 归档 + D2 清点 + 规范文件机械覆盖，**主控按第 2C 步按文件派写者 agent 做 D3~D5（主控只派不写），D6 / D7 是脚本机械动作** |

> ⭐ 版本戳是升级的唯一判据。**戳未盖 = 迁移未完成**，下次 `init` 仍判 Track D，不会把半成品误认为已完成。

> ⚠️ **Track C 也必须体检**（0.9.0 修正）：0.8.0 及以前 Track C「仅搬散落物」，**零格式体检**。一旦某文件盖戳时格式没归位，之后每次 `init` 都判 Track C 跳过检查 → **旧格式永久留存，永无自愈机会**。
> Track C 体检为**轻量版**：只检 D4 骨架清单，发现缺失即报主人并给归位建议，**不自动改写**（已最新的项目不该被 init 悄悄动内容）。

## 第 2 步：执行脚手架

```bash
bash "$CLAUDE_PLUGIN_ROOT/scripts/init.sh" "$(pwd)"
```

脚本按三轨自动分流。Track B/A 生成 `active/ backup/ docs/qa/ images/ scripts/ references/ design/ test/visual/baseline/` + **9 个 active 模板骨架**（按 L0~L4 分层：`Agent status` / `prd` / `ux` / `design` / `project data api` / `gates`）+ `bugs.md`（0.13.0 起，debug 链施工便签，常态为空）+ `references/` 经验库骨架（`INDEX.md` + `archive/` + `log/`，见下「经验库与权限」）+ **根目录 `CLAUDE.md` 入口引导** + **`.cc_code/README.md` 使用手册**（每次 init 无条件刷新到最新版，版本号取插件版本）+ **版本戳**。Track C 搬散落物 + 补建缺失的 `bugs.md` + 刷新手册 + 补建经验库骨架与权限 + 补建设计目录与截图基线目录 + **主控跑 D4 轻量骨架体检（只读报告，不改文件）**。Track D 见第 2C 步（脚本 D2 阶段自动补建缺失的经验库骨架与 `bugs.md`，D2.5 之后合并权限）。

子命令（供 AI 在升级阶段调用）：

| 命令 | 用途 |
| --- | --- |
| `bash init.sh --relocate <相对路径...>` | 冗余归位：`mv` 进 `backup/YYYY-MM/superseded/`。**零删除**，且拒绝归位规范 9 文件 |
| `bash init.sh --stamp` | 盖版本戳。**仅在 D5 校验门全过后才允许调用** |

### 经验库与权限（⭐1.10.0 新增，三轨通用，脚本机械动作，幂等）

经验沉淀由 curator 静默完成，init 只负责把它要用的地方和权限一次配好。规则出处 `Agent.md` §四 第 7 条，整理细则见 `agents/curator.md`，本命令不复述。

| 脚本动作 | 位置 | 说明 |
| --- | --- | --- |
| 建项目经验库 | `.cc_code/references/` | `INDEX.md` + `archive/` + `log/`（`adoption.md` `active-days.md` `processed.md` `started` `reminded`）；缺什么补什么，已有的一个字不动；旧主题文件原样保留 |
| 建个人经验库 | `~/.cc-code/lessons/` | 同结构（`log/` 里改为 `adoption.md` `active-days.md` `team-pull.md`）；建失败只告警，不挡 init |
| 合并项目权限 | `.claude/settings.local.json`（含本机绝对路径，只对本机生效，默认不入 git） | 加入 `permissions.additionalDirectories` 的 `$HOME/.cc-code`（展开后的绝对路径），以及 `permissions.allow` 的 `~/.cc-code/**` 读与改、项目库 `.cc_code/references/**` 的改、`printf` 追加（追加目标另按改文件规则检查）、团队库克隆与精确匹配的快进拉取两条 git 命令。已有设置原样保留，重复运行不重复加 |

- 合并工具：有 `jq` 用 `jq`，没有退 `python3`；两者都没有就只告警并打印要手动加的条目，不动文件。
- 改动已有 `settings.local.json` 前，原文件快照到 `backup/YYYY-MM/settings.local.json.pre-merge`；文件不是合法 JSON 则不碰，只告警。
- 团队库 `~/.cc-code/team/<仓库名>/` 不由脚本建，主人给出 git 地址时由 curator 克隆。
- `log/started` 是 curator 的开工时间戳，`log/reminded` 是 Stop hook 的「已提醒」记号；插件 Stop hook（`hooks/hooks.json` → `hooks/curator-reminder.sh`，随插件注册，不由 init 安装）只比它们与 `gates.md` 的修改时间。

散落物迁移采用**「默认不动」判定链**（任一命中即跳过）：① 保护白名单 → ② **git 已追踪**（最强判据：人 commit 过 = 不是垃圾）→ ③ 被 package.json/CI/Dockerfile/源码引用 → 三关全过才做正向识别（名字像临时物/过程报告才搬）→ ④ 都不匹配则**原地保留**并记入 `backup/YYYY-MM/needs_review.md` 交人工判断。搬走的记入 `migration_manifest.md`。同时把 `.cc_code/backup/` 追加进根 `.gitignore`。

> ⚠️ 判定链宁可漏搬也绝不误杀 —— `setup.py` / `manage.py` / `conftest.py` / `AGENTS.md` / `build.sh` / `logo.png` 这类项目基建必须原地不动。

CLAUDE.md 处理（init.sh 自动完成，机械活）：

- **Track B 新项目**：直接 `cp templates/CLAUDE.md → 根目录/CLAUDE.md`。
- **Track A 旧项目**：先把旧 `CLAUDE.md` 备份至 `.cc_code/backup/YYYY-MM/CLAUDE.md.legacy`，再用入口模板覆盖根目录 `CLAUDE.md`。
- **Track D 升级**：D1 快照之后，脚本把 `active/Agent.md`、根目录 `CLAUDE.md`、`AGENTS.md` 机械覆盖为插件模板新版，旧版快照进 `backup/YYYY-MM/pre-upgrade-<旧版>/spec/`。这三件是插件规范文件，唯一写者 = init 脚本，项目不自定义 `Agent.md` 权限，项目差异一律写进 `project.md`；脚本不改任何其它已存在文件的内容。

> 新生成的 `CLAUDE.md` 是**纯入口引导**（会话开启协议 + 三铁律 + 文件索引），不含任何业务状态。Claude Code 原生会自动加载它，从而被引导进 `.cc_code/` 状态机。

## 第 2B 步：codegraph 装载引导（⭐0.10.0 新增，三轨通用）

`init.sh` 的 `ensure_codegraph()` 已做完**探测与建索引**（静默，不阻塞）。AI 只需处理一种情况：脚本输出 `CODEGRAPH_MISSING`。

### 静默五铁则（AI 必须遵守）

```
① 零新增用户命令   人永不需要敲 codegraph 任何子命令
② 零阻塞           建索引后台跑，init 绝不等它
③ 零噪音           已就绪时一个字都不提（⛔ 禁报「索引正常」这类废话）
④ 只在异常说一行   未装 / 库损坏 / 建议重建
⑤ 永不自动全量重建 index 可能耗时数分钟，只提示不执行
```

### 命中 `CODEGRAPH_MISSING` 时：用 `AskUserQuestion` 弹一次选择框

⛔ 禁止静默跳过（人会永远不知道自己少了什么），⛔ 禁止脚本自动 `npm i -g`（改全局环境是高风险操作，必须人点头）。

选择框必须讲清**装了得到什么**：

| 能力 | 装了 | 不装（降级形态） |
| :--- | :--- | :--- |
| 增量规划爆炸半径 | `impact` 算传递闭包，改一处知道炸到哪 | Glob/Grep 表层猜测，半径估偏 |
| 冗余检测 | 自动扫死代码 / 孤儿文件 / 重复实现 | `agent-whole-qa` 冗余项基本瞎 |
| 精准回归 | `affected` 算出只需跑的测试 | 全量跑，QA 时间成本高 |
| 契约校准 | Architect 自动核对 `api.md` / `data.md` 实现状态 | 手工 Grep 核对，易漏 |

- 选项 A「安装（推荐）」→ 执行 `npm i -g @colbymchenry/codegraph`（**注意包名带 scope**，裸 `codegraph` 是另一个包），装完依次跑 `codegraph install -y`（注册 MCP）→ `codegraph init`（建索引，后台）。
- 选项 B「跳过」→ 记一行到 `status.md`「当前卡点」，本次会话不再问。

> 安装是**一次性**动作。之后 watcher 自动追写 + daemon 复活时 catch-up 补账，人永不需要手动 sync。

### 索引体检（库已存在时，AI 读 `codegraph status --json` 三字段）

| 字段 | 命中 | 动作 |
| :--- | :--- | :--- |
| `initialized: false` | 库损坏 | 报一行，⛔ 不自动重建 |
| `pendingChanges` 非 0 | 有未追写改动 | 静默跑一次 `codegraph sync`（新鲜度保险） |
| `reindexRecommended: true` | 引擎版本升级过 | 报一行建议 `codegraph index -f`，⛔ 不自动执行 |

### `.cc_code/test/` 是测试代码目录（⛔ 绝不 ignore）

`init.sh` 新建 `.cc_code/test/`，且 `update_gitignore()` 只 ignore `backup/` 与**临时产物子目录**（`.cc_code/docs/qa/artifacts/`、`coverage/`、`test-results/`），并写入注释警告。**测试代码是源码，被 ignore 就不进 codegraph 索引 → `affected` 永久失效**。同样必须入库的还有：`.cc_code/design/`（方向卡与样板板）、`.cc_code/test/visual/`（视觉测试）与 `baseline/`（截图基线）；⛔ 不许用 `*.png` / `screenshots/` 全局通配忽略截图。测试 glob 由 Architect 登记在 `project.md` §六。

## 第 2B' 步：前端风格与视觉目录（⭐1.11.0 改）

**本命令不问、不建任何设计稿文件。** 前端风格一律走 `/cc-code:plan-uiux`（模式一 定风格 / 模式二 改版），唯一视觉事实源是 `active/design.md`；旧项目根目录的 `design.pen` **原地保留：不读、不写、不转换**，也不再是视觉事实源。

`init.sh` 只做两件机械事，三轨通用：

| 目录 | 写者 | 入库 | 说明 |
| :--- | :--- | :--- | :--- |
| `.cc_code/design/` | uiux | ✅ 必须入 git | 方向卡、风格样板板与样板板截图（不是项目代码） |
| `.cc_code/test/visual/baseline/` | qa 独占 | ✅ 必须入 git | 截图基线；同目录放允许值集合夹具 |

- 升级轨做一次**机械前端探测**（`package.json` 前端依赖，或源码里的页面组件文件）：无前端 → `design.md` 只建骨架并把状态标成「不适用（无前端）」，**不派 uiux**；有前端 → 建空骨架，交给 uiux 按审计迁移。
- 忽略口径：只忽略临时产物（`docs/qa/artifacts/`、`coverage/`、`test-results/`）；⛔ 不许全局忽略截图，设计目录与基线必须入库。

From weiyi88/cc-code, MIT.

More from weiyi88/cc-code