diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3f443db
--- /dev/null
+++ b/README.md
@@ -0,0 +1,189 @@
+# loop-build 使用指南（简体中文）
+
+本文件是 `loop-build (Codex CLI harness)` 的中文操作手册，面向日常使用者。  
+目标是让你按固定节奏推进任务：**先计划、再审批、单步执行、验证、再次审批**。
+
+## 1. 这套 harness 是做什么的
+
+`loop-build` 用于长时间运行、可中断、可回滚的任务执行。  
+它把一次任务拆成 3~7 个步骤，并强制执行以下状态机：
+
+1. 生成 PLAN  
+2. 人类审批 PLAN（`APPROVE_PLAN / REVISE_PLAN / CANCEL_TASK`）  
+3. 每次只执行 1 个 step  
+4. step 后汇报并等待下一次审批（`APPROVE_NEXT / REVISE_PLAN / CANCEL_TASK`）  
+
+## 2. 首次使用（一次性）
+
+在仓库根目录执行：
+
+```bash
+./.loop-build/scripts/init.sh
+```
+
+初始化脚本会：
+- 检查依赖：`git`、`bash`、`rg`、`jq`
+- 初始化 `.loop-build` 所需目录与默认配置
+- 生成任务模板与状态文件（若缺失）
+- 提示你尽量在 git 工作树较干净时开始
+
+## 3. 每个任务的标准流程
+
+### 第一步：准备任务输入
+
+你需要准备 4 类输入给 planner：
+- `goal`：任务目标
+- `constraints`：约束条件
+- `repo_context_hint`：仓库上下文提示
+- `current_state_summary`：当前状态摘要（可选）
+
+### 第二步：产出并写入 PLAN
+
+用 `./.loop-build/prompts/planner.md` 让 Codex 生成严格 JSON，写入：
+
+```bash
+./.loop-build/state/current_task.json
+```
+
+PLAN 必须满足：
+- 步数 3~7
+- 每步包含：
+  - `step_id`
+  - `action`
+  - `verification`
+  - `rollback`
+  - `risk_level`
+  - `expected_output`
+
+### 第三步：审批 PLAN（强制）
+
+```bash
+./.loop-build/scripts/run_task.sh APPROVE_PLAN
+```
+
+如果要改计划：
+
+```bash
+./.loop-build/scripts/run_task.sh REVISE_PLAN "说明你要改什么"
+```
+
+取消任务：
+
+```bash
+./.loop-build/scripts/run_task.sh CANCEL_TASK
+```
+
+### 第四步：单步执行
+
+```bash
+./.loop-build/scripts/run_task.sh step
+```
+
+或指定步号：
+
+```bash
+./.loop-build/scripts/run_task.sh step 2
+```
+
+执行特性：
+- 一次只推进一个 step
+- 默认输出 unified diff，不整文件倾泻
+- 按 step 的 `verification` 决定是否触发验证
+- 写入历史记录到 `state/history.ndjson`
+- 更新 `current_task.json` 的进度字段
+
+### 第五步：每步后再次审批
+
+```bash
+./.loop-build/scripts/run_task.sh APPROVE_NEXT
+```
+
+或要求改计划：
+
+```bash
+./.loop-build/scripts/run_task.sh REVISE_PLAN "下一步前先调整计划"
+```
+
+然后继续 `step`，直到完成。
+
+## 4. 常用命令速查
+
+查看当前任务状态：
+
+```bash
+./.loop-build/scripts/run_task.sh status
+```
+
+执行验证（手动）：
+
+```bash
+APPROVE=1 ./.loop-build/scripts/verify.sh unit
+APPROVE=1 ./.loop-build/scripts/verify.sh lint
+APPROVE=1 ./.loop-build/scripts/verify.sh typecheck
+APPROVE=1 ./.loop-build/scripts/verify.sh all
+```
+
+创建快照：
+
+```bash
+./.loop-build/scripts/snapshot.sh
+./.loop-build/scripts/snapshot.sh before-step-2
+```
+
+## 5. 安全策略说明（必须了解）
+
+策略文件在 `./.loop-build/config/`：
+- `allowlist.txt`：默认允许的只读命令
+- `denylist.txt`：默认禁止的高风险命令
+- `policy.env`：显式解锁开关
+
+关键点：
+- 命令会按分段检查（如 `&&`、`||`、`;`、`|`）
+- 命中 denylist 默认拦截
+- 需在 `policy.env` 显式解锁并启用二次确认，才允许执行高风险动作
+
+## 6. 实战建议（推荐）
+
+- 每个 step 只做一个最小可验证改动（MVC）。
+- 每个 step 最多改 2 个文件，超过就拆分计划。
+- `action` 尽量写成可直接执行的最小命令列表。
+- `verification` 只写当前 step 真正需要的 target，避免全量跑。
+- 每步都写清 rollback，失败时能快速恢复。
+- 发现计划偏离时优先 `REVISE_PLAN`，不要硬推进。
+
+## 7. 常见问题排查
+
+`run_task.sh` 提示 plan 未审批：
+- 先执行 `APPROVE_PLAN`。
+
+验证被阻止：
+- 手动运行 verify 时需要 `APPROVE=1`。
+
+step 被策略拦截：
+- 查看 denylist 命中原因。
+- 评估是否真的需要解锁，不建议为省事放开高风险命令。
+
+快照文件需要检查：
+
+```bash
+latest=$(ls -1t ./.loop-build/state/snapshots/snapshot-*.json | head -n 1)
+jq . "$latest"
+```
+
+## 8. 推荐协作模板（给 Codex CLI）
+
+你可以直接用下面这段话发起任务：
+
+```text
+请基于 .loop-build/prompts/planner.md 生成严格 JSON 计划，目标是：
+<goal>
+约束是：
+<constraints>
+仓库上下文：
+<repo_context_hint>
+当前状态：
+<current_state_summary>
+要求 3~7 步，每步包含 step_id/action/verification/rollback/risk_level/expected_output。
+```
+
+生成后先写入 `state/current_task.json`，再走审批与 step 循环。