Init Codebase — Make any repo agent-ready

一键初始化任意代码仓库，变成 agent 友好 的知识库 + 自动化工作空间。

基于 loop-engineer-template 的知识库模型，由 Trading Pi OS 的实战经验提炼而成。

---

什么是 Init Codebase？

这是一个 Claude Code skill。你在任意代码仓库里运行它，它会：

1. 注入知识库模型 — ARCHITECTURE.md、signals/、domains/、LOG.md、docs/ 的 schema
2. 注入 Agent Harness — 内置 5 个 skills（new-loop、setup-codebase-harness、dev-local-setup、e2e-setup、pr）和 1 个 workflow（ship-change.js）
3. 适配现有文档 — 更新 CLAUDE.md、docs/README.md

让你的代码仓库从一个纯代码目录，变成一个 Agent 可以自主工作、积累知识、持续改进 的智能工作空间。

它解决了什么问题？

问题	解决方式
Agent 每次会话都要重新理解项目	CLAUDE.md + ARCHITECTURE.md 提供持久化的 Operating Context
Agent 学到的知识不能跨会话复用	signals/ + docs/ + LOG.md 提供文件化的知识积累
没有结构化的日志	LOG.md 提供 append-only 的全局工作日志
Agent 的工作线程没有归属	domains/ 提供 loop 组织框架
缺少自动化的 CI 工具	内置 skills（dev-local-setup, e2e-setup, pr, ship-change）

---

安装

方式一：从 GitHub 克隆（推荐）

# 克隆到 Claude Code 的 skills 目录
git clone https://github.com/lora-sys/Init-codebase.git /path/to/.claude/skills/init-codebase

# 或者克隆到任意位置，然后在 Claude Code 中引用
git clone https://github.com/lora-sys/Init-codebase.git ~/skills/init-codebase

Claude Code 会自动发现 .claude/skills/ 下的 skill。

方式二：手动安装

1. 下载仓库: git clone https://github.com/lora-sys/Init-codebase.git
2. 将 Init-codebase/ 整个文件夹复制到你的 .claude/skills/ 目录下
3. 或者放在任意位置，Claude Code 会通过权限对话框自动识别

方式三：直接 .skill 文件

# 如果有 .skill 文件包
pip install --user skill-installer  # 可选安装工具
skill install init-codebase.skill

---

使用

在 Claude Code 中运行

在目标仓库的会话中：

/init-codebase /path/to/your/repo

或者用 skill 的完整名称触发（自动匹配 init-codebase 描述）。

在命令行中直接运行

# 找到 skill 目录
SKILL_DIR=~/.claude/skills/init-codebase

# 运行 scaffold 脚本
bash $SKILL_DIR/scripts/scaffold-codebase.sh /path/to/your/repo

# 忽略 git 检查（非 git 仓库）
bash $SKILL_DIR/scripts/scaffold-codebase.sh /path/to/your/repo --force

运行后步骤

初始化完成后，需要做这些：

1. 检查 CLAUDE.md — 如果它已存在但没有 Knowledge base 章节，手动添加（脚本会提示）
2. 更新 AGENTS.md（如有）—— 添加知识库约定和 worktree 规范
3. 创建第一个 loop — 在目标仓库中运行 /new-loop
4. 提交初始化文件:

git add ARCHITECTURE.md LOG.md signals/ domains/ docs/README.md
git commit -m "feat: init loop-engineer knowledge base and agent harness"

---

Skill 包含什么

init-codebase/
├── SKILL.md                              # Skill 主文件（Claude Code 读取的指令）
├── README.md                             # 本文件
├── scripts/
│   └── scaffold-codebase.sh              # 主干脚本：复制模板、适配文档、安装 skills
├── references/
│   └── template-architecture.md          # 知识库架构设计原理解析
└── assets/
    └── loop-engineer-harness/            # 注入目标仓库的模板文件
        ├── ARCHITECTURE.md               # 知识库架构说明书
        ├── LOG.md                        # 全局工作日志模板
        ├── CLAUDE.md                     # CLAUDE.md 模板（含 {{PLACEHOLDER}}）
        ├── signals/README.md             # 信号 schema
        ├── domains/README.md             # Loop schema
        └── docs/README.md                # Docs schema 头部

注入的 Skills（到目标仓库的 .claude/skills/）

Skill	功能
new-loop	创建新的 domain loop——scaffold README、测试运行、记录结果
setup-codebase-harness	完整的代码仓库环境配置（legible、executable、verifiable）
dev-local-setup	一键配置本地开发环境（tmux 多服务启动脚本）
e2e-setup	配置端到端测试套件（Playwright、视频记录、可复用的 auth helper）
pr	验证 -> 创建 PR（新 sub-agent 先验证功能再开 PR）

注入的 Workflows（到目标仓库的 .claude/workflows/）

Workflow	功能
ship-change.js	端到端代码提交：worktree 隔离 -> 实现 -> review -> 验证 -> PR

---

知识库模型速览

两种核心 Artifact

种类	目录	说明
signal	signals/	原始证据：反馈、想法、观察（去重+计频）
doc	docs/	耐久知识：分析、决策、学到的东西

Domains（Loop）

每个 loop 是一个可独立运行的工作线程，有自己的 charter、cadence 和 metrics。 每个 loop 的 README.md 包含：goal、backlog、evidence links、metrics、Timeline。

日志

• 每个 artifact 有 append-only 的 ## Timeline
• 全局日志 LOG.md：每完成一批工作追加一行

原则

• One concept = one home（每个概念只有一个归宿）
• domain: 是字段，不是文件夹（跨域用标签+链接）
• Body = what's true now；Timeline = what happened
• Frontmatter = 需要查询的东西；Prose = 剩下的
• Default to doc or signal（不要随便创建新 kind）

---

工作原理

流程

用户输入 /init-codebase <target-dir>
  ↓
SKILL.md 被加载到上下文
  ↓
Claude Code 执行流程：
  1. 确认目标目录
  2. 运行 scaffold-codebase.sh
  3. 验证注入结果
  4. 提供后续步骤提示

scaffold 脚本的具体行为

flowchart LR
    A[目标仓库] --> B{检查 .git?}
    B -->|是| C[复制知识库模板]
    B -->|否| D[--force 跳过检查]
    D --> C
    C --> E[更新 docs/README.md]
    E --> F[检查 CLAUDE.md]
    F -->|缺少 KB 章节| G[给出提示]
    F -->|已存在| H[安装 .claude skills]
    H --> I[完成]

Loading

---

定制指南

修改注入的模板文件

直接编辑 assets/loop-engineer-harness/ 下的文件即可自定义注入内容。

修改 scaffold 行为

编辑 scripts/scaffold-codebase.sh。

添加/删除 bundled skill

• 添加：在 assets/loop-engineer-harness/dot-claude/skills/ 下创建新 skill 目录
• 删除：直接删除对应的 skill 目录

---

许可证

MIT

相关项目

• loop-engineer-template — 此 skill 的知识库模型来源
• Trading Pi OS — 实战验证此模型的交易操作系统
• AI Builder Club — Jason Zhou 的 Loop Engineer 课程