diff --git a/.loop-build/QUICKSTART.md b/.loop-build/QUICKSTART.md
new file mode 100644
index 0000000..a1a19f4
--- /dev/null
+++ b/.loop-build/QUICKSTART.md
@@ -0,0 +1,93 @@
+# loop-build 快速开始（5 分钟上手）
+
+这是一份“少解释、直接跑”的版本。
+
+## 一、最短路径（照抄即可）
+
+1. 初始化：
+
+```bash
+./.loop-build/scripts/init.sh
+```
+
+2. 让 Codex 生成计划，并写入：
+
+```bash
+./.loop-build/state/current_task.json
+```
+
+3. 审批计划：
+
+```bash
+./.loop-build/scripts/run_task.sh APPROVE_PLAN
+```
+
+4. 执行一步：
+
+```bash
+./.loop-build/scripts/run_task.sh step
+```
+
+5. 通过后放行下一步：
+
+```bash
+./.loop-build/scripts/run_task.sh APPROVE_NEXT
+```
+
+6. 重复第 4、5 步直到完成。
+
+---
+
+## 二、你只需要记住这 6 条命令
+
+```bash
+./.loop-build/scripts/init.sh
+./.loop-build/scripts/run_task.sh status
+./.loop-build/scripts/run_task.sh APPROVE_PLAN
+./.loop-build/scripts/run_task.sh step
+./.loop-build/scripts/run_task.sh APPROVE_NEXT
+APPROVE=1 ./.loop-build/scripts/verify.sh unit
+```
+
+---
+
+## 三、三种常见“下一步”
+
+计划不合适：
+
+```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 status
+```
+
+---
+
+## 四、避免踩坑（精简版）
+
+- 每次 `step` 只改一小块，别贪大。
+- step 结束后先 `APPROVE_NEXT`，再继续下一步。
+- 手动跑验证时必须加 `APPROVE=1`。
+- 遇到策略拦截先看提示，不要直接放开高风险命令。
+
+---
+
+## 五、给 Codex 的最短提示词
+
+```text
+请按 .loop-build/prompts/planner.md 生成严格 JSON 计划（3~7步），并写入 .loop-build/state/current_task.json。
+目标：<goal>
+约束：<constraints>
+上下文：<repo_context_hint>
+现状：<current_state_summary>
+```
diff --git a/README.md b/README.md
index 3f443db..306385d 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,8 @@
 本文件是 `loop-build (Codex CLI harness)` 的中文操作手册，面向日常使用者。  
 目标是让你按固定节奏推进任务：**先计划、再审批、单步执行、验证、再次审批**。
 
+> 快速开始 [QUICKSTART.md](.loop-build/QUICKSTART.md)
+
 ## 1. 这套 harness 是做什么的
 
 `loop-build` 用于长时间运行、可中断、可回滚的任务执行。