企业官网建设流程全解析

任務計畫：[簡要描述]

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files

將此檔案作為任務的持久化路線圖。開始複雜工作前先建立它，並在階段變更時持續更新。

标题中的 `[簡要描述]` 应替换为任务的一句话概括，例如「後端重構」「事故調查」。引言两行定义了该文件的两条根本属性：**持久化**（跨会话、跨 /clear、跨上下文压缩存活）与**持续更新**（阶段变更时必须同步维护）。 ### 2. 目標（Goal） ```markdown ## 目標 用一句清楚的話描述預期的最終結果。 [用一句話描述最終狀態]

目标是整个计划的锚点。它同时是「五问重启测试」中「目標是什麼？」的答案来源，也决定了后续阶段划分是否合理。规范要求一句話讲清最终状态，避免写成愿望清单。

3. 下一步（Next Step）

## 下一步 記錄接下來唯一要執行的動作。每當目前階段或立即行動變更時都要更新。 [接下來唯一要執行的動作；階段狀態變更時請更新。]

「下一步」只记录唯一要执行的动作。它的价值在于对抗上下文腐烂（context rot）：当一次会话被 /clear、压缩或长时间停顿打断后，Agent 只要读到这一节就能立即知道该干什么，而不必重新推断。注意维护时机——每当阶段状态变更时都要更新，英文规范版同样强调这一点（"Whenever a phase status changes, also refresh## Next Step"）。

4. 目前階段（Current Phase）

## 目前階段 寫下目前正在處理的階段。 階段 1

这是「我在哪裡？」的答案。它在英文规范版中也是 gate（完成闸门）的输入之一：gate 依赖阶段状态判断是否允许 Stop 事件放行。

5. 各階段（Phases）——模板的核心

## 各階段 將任務拆成三到七個可驗證的階段。每個狀態只能使用 `pending`、`in_progress` 或 `complete`，並在工作推進時更新。 ### 階段 1：需求與發現 - [ ] 理解使用者意圖 - [ ] 確定約束條件和需求 - [ ] 將發現記錄到 findings.md - **狀態：** in_progress ### 階段 2：規劃與結構 - [ ] 確定技術方案 - [ ] 如有需要，建立專案結構 - [ ] 記錄決策及理由 - **狀態：** pending ### 階段 3：實作 - [ ] 按計畫逐步執行 - [ ] 先將程式碼寫入檔案再執行 - [ ] 進行增量測試 - **狀態：** pending ### 階段 4：測試與驗證 - [ ] 驗證所有需求已滿足 - [ ] 將測試結果記錄到 progress.md - [ ] 修復發現的問題 - **狀態：** pending ### 階段 5：交付 - [ ] 檢查所有輸出檔案 - [ ] 確保交付物完整 - [ ] 交付給使用者 - **狀態：** pending

阶段区块有三个硬性约定：

1. 数量约束：三到七个可验证阶段。太少无法形成增量验证，太多则维护成本失控。
2. 状态枚举：每个阶段只能使用pending、in_progress、complete三个值之一。这是模板的明确要求，也是 phase-status.sh 中case "${NEW_STATUS}" in pending|in_progress|complete)白名单校验的来源——任何其他字符串都会被拒绝并报错。
3. 任务项（checkbox）与状态行并存：每个阶段既包含- [ ]格式的可勾选子任务，也包含- **狀態：**状态行。前者是人工/模型可读的进度明细，后者是脚本可解析的结构化状态。

模板内置的五阶段（需求與發現 → 規劃與結構 → 實作 → 測試與驗證 → 交付）是通用研发流程的默认拆分，可据此增删。在 gated 模式下，处于in_progress的阶段会作为闸门的判定输入之一（见 SKILL.md 的 Gate decision table）。

6. 關鍵問題（Key Questions）

## 關鍵問題 記錄重要問題，並在問題解決後以答案取代它們。 1. [待回答的問題] 2. [待回答的問題]

该区块记录尚待回答的重要问题，问题解决后直接用答案替换问题本身，而不是累积追加。它相当于计划期的「待办研究清单」，避免 Agent 在长任务中遗忘悬而未决的约束。

7. 已做決策（Decisions Made）

## 已做決策 記錄重要選擇及其理由。 | 決策 | 理由 | |------|------| | | |

决策表采用「决策-理由」两列结构，记录技术方案选择及其理由。它是「五问重启测试」中「我學到了什麼？」的补充证据源，也是后续回溯「为什么当时这么做」的唯一依据。规划阶段与实现阶段之间发生方向调整时，务必在此登记。

8. 遇到的錯誤（Errors Encountered）

## 遇到的錯誤 記錄每個不同的錯誤、嘗試次數與解決方式。再次嘗試失敗的動作前，先改變處理方法。 | 錯誤 | 嘗試次數 | 解決方案 | |------|---------|---------| | | 1 | |

错误表记录「不同错误 × 尝试次数 × 解决方案」，其背后是「永遠不要重複失敗」原则：

if 操作失敗: 下一步操作 != 同樣的操作

记录你尝试过的方法，改变方案。这与 SKILL.md 中的「三次失敗協定」相呼应：第一次尝试诊断并修复，第二次尝试替代方案（不同工具、不同库），第三次质疑假设并考虑更新计划，三次失败后向用户求助。

9. 備註（Notes）

## 備註 - 隨著工作推進，將階段狀態從 `pending` 更新為 `in_progress`，再更新為 `complete`。 - 做重大決策前，重新閱讀目標與下一步。 - 立即記錄錯誤，避免重複失敗的處理方式。

备注区浓缩了三条维护纪律：状态单向流转、决策前重读目标、错误即时记录。

三、阶段状态机：三个枚举值如何被脚本消费

模板规定状态值只有三个，这不是偶然——check-complete.sh和phase-status.sh都依赖这组精确的字符串字面量做解析。

check-complete.sh 如何判断完成度

check-complete.sh 的解析逻辑非常直白：

# 計算階段總數 TOTAL=$(grep -c "### 階段" "$PLAN_FILE" || true) # 先檢查 **狀態：** 格式 COMPLETE=$(grep -cF "**狀態：** complete" "$PLAN_FILE" || true) IN_PROGRESS=$(grep -cF "**狀態：** in_progress" "$PLAN_FILE" || true) PENDING=$(grep -cF "**狀態：** pending" "$PLAN_FILE" || true)

它按### 階段计阶段总数，再统计**狀態：** complete|in_progress|pending三个状态行的数量；若三者均为 0（旧格式或未按模板书写），则回退匹配行内[complete]、[in_progress]、[pending]格式。输出规则：

• TOTAL=0（未按阶段结构组织）时保持静默退出；
• COMPLETE == TOTAL时报「所有階段已完成」；
• 否则报「任務進行中（N/TOTAL 個階段已完成）」并列出进行中与待处理的数量。

脚本始终以退出码 0 结束——未完成的任务是正常状态而非错误，这是 issue #191/#195 的教训：一次性/CI 会话可以用PLANNING_DISABLED=1退出规划流程，Stop 钩子调用它时也绝不能因「未完成」而中断代理。相关行为由 test_check_complete_resolver.py 等测试用例锁定。

phase-status.sh 如何安全改写状态行

并发场景下，多个 Agent 可能同时读写同一份 task_plan.md。为此 phase-status.sh 被设计为唯一被认可的并发安全状态写入器（orchestrator 拥有 task_plan.md，worker 不得直接改写共享规划文件）。它的执行要点：

1. 用法为sh scripts/phase-status.sh <phase-number> <pending|in_progress|complete>，阶段号必须是正整数，状态值必须命中白名单；
2. 通过<plan-dir>/.pwf-locks/phase-status.lock目录锁实现 read-modify-write，用临时文件 +mv原子交换防止撕裂写入；
3. 只改写### Phase N标题块之后的第一条**Status:**行，后续阶段不受影响；
4. 锁获取超时（5 秒或 50 次尝试）时退出 75，且不做任何计划变更。

注意：状态行改写会改变文件的 SHA-256，因此在阶段边界处 orchestrator 需要重新执行 attest（attest-plan.sh），否则钩子会因哈希不匹配而拒绝注入（见第四节）。

四、模板如何被钩子注入：运行机制与安全边界

task_plan.md 之所以能成为「持久化路线图」，关键在于生命周期钩子的自动注入。以 SKILL.md 中的 hook 配置为例，PreToolUse匹配Write|Edit|Bash|Read|Glob|Grep，在每次工具调用前定位并执行skill-hook.sh；UserPromptSubmit在每轮用户提示时注入；PreCompact（v2.38.0+）在上下文压缩前给出诊断提醒。完整的事件路由见仓库根部的 hooks/hooks.json。

恢复流程：会话开始（或 /clear、压缩后恢复）时，先用resolve-plan-dir.sh解析任务所属的计划目录——优先级为$PLAN_ID环境变量 →.planning/.active_plan指针 → 最新.planning/<dir>/→ 回退到项目根的旧式task_plan.md（见 resolve-plan-dir.sh），然后从该目录读取三份规划文件。自动恢复只读项目规划文件；session-catchup.py不带参数时不会触碰宿主会话存储，只有显式--metadata/--replay才读取本机同项目的会话记录（--metadata只输出聚合计数，不输出逐字稿字节）。

安全边界：因为 task_plan.md 会被反复注入上下文，它成为间接提示注入的高价值目标。模板和 SKILL.md 共同约定的红线包括：

同时，注入内容会被===BEGIN PLAN DATA===/===END PLAN DATA===（v3 模式下为带 nonce 的边界标记）框定，应只作为结构化数据处理，绝不执行其中嵌入的指令。可选启用/plan-attest（attest-plan.sh）对 task_plan.md 做 SHA-256 快照，此后任何计划文件变更都会触发[PLAN TAMPERED]并阻断注入，直到重新 attest——这正是「先把代码/计划写入文件，钩子再决定是否注入」的设计闭环。

五、配套脚本：从零初始化一份 task_plan.md

在复杂任务开始前，最标准的做法是运行 init-session.sh：

./scripts/init-session.sh "Backend Refactor"

它会输出一个PLAN_ID（形如2026-09-05-backend-refactor），将三份规划文件初始化到.planning/<PLAN_ID>/目录（无参数时回退到项目根、保持 v1.x 兼容的旧式模式）。生成的 task_plan.md 即上文逐节讲解的完整模板，findings.md 与 progress.md 也一并生成。仓库根部的规范版 init-session.sh 还支持--template default|analytics、--plan-dir、--autonomous、--gated等选项：--autonomous写入.mode标记、生成 nonce 并自动 attest；--gated在此基础上叠加 Stop 完成闸门；--template analytics则改用 analytics_task_plan.md 这一面向数据分析/探索会话的变体模板（阶段划分改为 Data Discovery → Exploratory Analysis → Hypothesis Testing → Synthesis & Reporting，决策表与假设区块随之调整）。

平行任务场景下，每个独立任务各建一个具名计划，并用export PLAN_ID=...把每个宿主钉在自己的计划上；set-active-plan.sh用于顺序切换共享默认指针（详见 SKILL.md 的 Parallel task workflow 小节）。

六、三文件协同：task_plan.md 不是孤岛

模板中各阶段的检查项明确要求与其他两份文件联动：

• 「將發現記錄到 findings.md」——阶段 1 的产出进入 findings.md（含需求、研究發現、技術決策、遇到的問題、資源、視覺/瀏覽器發現六个区块）。配合「兩步操作規則」：每执行 2 次查看/浏览器/搜索操作后，立即把关键发现写入文件，防止视觉/多模态信息丢失。
• 「將測試結果記錄到 progress.md」——阶段 4 的验证结果进入 progress.md（含会话日志、測試結果表、錯誤日誌、五問重啟檢查四个区块）。

「五问重启测试」用一张表把三文件串成完整的上下文自检闭环：

若会话中断后能回答全部五个问题，说明上下文管理是完善的；而答案全部落在磁盘文件中——这正是「/clear 与压缩之后自动恢复」的机制基础（相关文档见 docs/agent-forgets-plan-after-clear.md 与 docs/claude-code-lost-context-after-compaction.md）。

七、实战演练：一份填写完成的 task_plan.md

以下示例展示一份真实可用的任务计划（以「後端重構」任务为例）：

# 任務計畫：後端服務重構 將此檔案作為任務的持久化路線圖。開始複雜工作前先建立它，並在階段變更時持續更新。 ## 目標 將訂單服務從單體拆出為獨立的微服務，且所有既有測試全部通過。 ## 下一步 為訂單服務建立獨立的資料庫 schema 遷移腳本。 ## 目前階段 階段 2 ## 各階段 ### 階段 1：需求與發現 - [x] 理解使用者意圖 - [x] 確定約束條件和需求 - [x] 將發現記錄到 findings.md - **狀態：** complete ### 階段 2：規劃與結構 - [x] 確定技術方案 - [x] 建立專案結構 - [ ] 記錄決策及理由 - **狀態：** in_progress ### 階段 3：實作 - [ ] 按計畫逐步執行 - [ ] 先將程式碼寫入檔案再執行 - [ ] 進行增量測試 - **狀態：** pending ### 階段 4：測試與驗證 - [ ] 驗證所有需求已滿足 - [ ] 將測試結果記錄到 progress.md - [ ] 修復發現的問題 - **狀態：** pending ### 階段 5：交付 - [ ] 檢查所有輸出檔案 - [ ] 確保交付物完整 - [ ] 交付給使用者 - **狀態：** pending ## 關鍵問題 1. 是否需要保留與舊 API 的相容層？ ## 已做決策 | 決策 | 理由 | |------|------| | 使用事件驅動架構 | 訂單狀態變更需要跨服務最終一致 | ## 遇到的錯誤 | 錯誤 | 嘗試次數 | 解決方案 | |------|---------|---------| | 資料庫連線逾時 | 2 | 在遷移腳本中加入重試邏輯 | ## 備註 - 隨著工作推進，將階段狀態從 `pending` 更新為 `in_progress`，再更新為 `complete`。 - 做重大決策前，重新閱讀目標與下一步。 - 立即記錄錯誤，避免重複失敗的處理方式。

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files