常見問題與故障排除

學完你能做什麼

快速定位和解決初始化時的目錄問題
排查 AI 助手啟動失敗的原因
理解階段失敗的處理流程（重試/回滾/人工介入）
解決依賴安裝和版本衝突問題
處理 Agent 越權錯誤
使用 factory continue 分會話恢復執行

你現在的困境

你可能遇到了這些問題：

❌ 執行 factory init 時提示"目錄非空"
❌ AI 助手無法啟動，不知道如何設定權限
❌ 管線執行到某個階段突然失敗，不知道如何繼續
❌ 依賴安裝報錯，版本衝突嚴重
❌ Agent 生成產物被標記為"越權"
❌ 不理解檢查點和重試機制

別擔心，這些問題都有明確的解決方案。本教學會幫你快速排查和修復各類故障。

🎒 開始前的準備

前置知識

開始前，請確保你已經：

[ ] 完成了安裝與設定
[ ] 完成了初始化 Factory 專案
[ ] 理解了 7 階段管線概覽
[ ] 知道如何使用 Claude Code 整合

核心思路

AI App Factory 的故障處理遵循一套嚴格的策略，理解這套機制會讓你在遇到問題時不再手足無措。

失敗處理的三個層次

自動重試：每個階段允許重試一次
回滾存檔：失敗產物移至 _failed/，回滾到上一個成功檢查點
人工介入：連續失敗兩次後暫停，需要你手動修復

越權處理規則

Agent 寫入未授權目錄 → 移至 _untrusted/
管線暫停，等待你審查
根據需要調整權限或修改 Agent 行為

權限邊界

每個 Agent 都有嚴格的讀寫權限範圍：

Agent	可讀取	可寫入
bootstrap	無	`input/`
prd	`input/`	`artifacts/prd/`
ui	`artifacts/prd/`	`artifacts/ui/`
tech	`artifacts/prd/`	`artifacts/tech/`, `artifacts/backend/prisma/`
code	`artifacts/ui/`, `artifacts/tech/`, `artifacts/backend/prisma/`	`artifacts/backend/`, `artifacts/client/`
validation	`artifacts/backend/`, `artifacts/client/`	`artifacts/validation/`
preview	`artifacts/backend/`, `artifacts/client/`	`artifacts/preview/`

初始化問題

問題 1：目錄非空錯誤

症狀：

bash

$ factory init
Error: Directory is not empty or contains conflicting files

原因：目前目錄包含衝突檔案（不是 .git、README.md 等允許的檔案）。

解決方案：

bash

ls -la

清理衝突檔案：

bash

# 方法 1：刪除衝突檔案
rm -rf <conflicting-files>

# 方法 2：移動到新目錄
mkdir ../my-app && mv . ../my-app/
cd ../my-app

重新初始化：

bash

factory init

允許的檔案：.git、.gitignore、README.md、.vscode/*、.idea/*

問題 2：已存在 Factory 專案

症狀：

bash

$ factory init
Error: This is already a Factory project

原因：目錄已包含 .factory/ 或 artifacts/ 目錄。

解決方案：

如果是新專案，先清理再初始化：

bash

rm -rf .factory artifacts
factory init

如果想恢復舊專案，直接執行 factory run

問題 3：AI 助手啟動失敗

症狀：

bash

$ factory init
✓ Factory project initialized
Could not find Claude Code installation.

原因：未安裝 Claude Code 或未正確設定。

解決方案：

安裝 Claude Code：

bash

# macOS
brew install claude

# Linux (從官網下載)
# https://claude.ai/code

驗證安裝：

bash

claude --version

手動啟動：

bash

# 在 Factory 專案目錄下
claude "請閱讀.factory/pipeline.yaml和.factory/agents/orchestrator.checkpoint.md，啟動管線"

手動啟動流程：1. 閱讀 pipeline.yaml → 2. 閱讀 orchestrator.checkpoint.md → 3. 等待 AI 執行

管線執行問題

問題 4：非專案目錄錯誤

症狀：

bash

$ factory run
Error: Not a Factory project. Run 'factory init' first.

原因：目前目錄不是 Factory 專案（缺少 .factory/ 目錄）。

解決方案：

確認專案結構：

bash

ls -la .factory/

切換到正確目錄或重新初始化：

bash

# 切換到專案目錄
cd /path/to/project

# 或重新初始化
factory init

問題 5：Pipeline 檔案未找到

症狀：

bash

$ factory run
Error: Pipeline configuration not found

原因：pipeline.yaml 檔案缺失或路徑錯誤。

解決方案：

檢查檔案是否存在：

bash

ls -la .factory/pipeline.yaml
ls -la pipeline.yaml

手動複製（如果檔案遺失）：

bash

cp /path/to/factory/source/hyz1992/agent-app-factory/pipeline.yaml .factory/

重新初始化（最可靠）：

bash

rm -rf .factory
factory init

階段失敗處理

問題 6：Bootstrap 階段失敗

症狀：

input/idea.md 不存在
idea.md 缺少關鍵章節（目標使用者、核心價值、假設）

原因：使用者輸入資訊不足，或 Agent 未正確寫入檔案。

處理流程：

1. 檢查 input/ 目錄是否存在 → 不存在則建立
2. 重試一次，提示 Agent 使用正確的範本
3. 若仍失敗，請求使用者提供更詳細的產品描述

手動修復：

bash

ls -la artifacts/_failed/bootstrap/

bash

mkdir -p input

提供詳細的產品描述：

向 AI 提供更清晰、更詳細的產品想法，包含：

目標使用者是誰（具體畫像）
核心痛點是什麼
想要解決什麼問題
初步的功能想法

問題 7：PRD 階段失敗

症狀：

PRD 包含技術細節（違反職責邊界）
Must Have 功能 > 7 個（範圍蔓延）
缺少非目標（未明確邊界）

原因：Agent 越界或範圍控制不嚴。

處理流程：

1. 驗證 prd.md 不包含技術關鍵字
2. 驗證 Must Have 功能數量 ≤ 7
3. 驗證目標使用者有具體畫像
4. 重試時提供具體的修正要求

常見錯誤範例：

錯誤類型	錯誤範例	正確範例
包含技術細節	"使用 React Native 實現"	"支援 iOS 和 Android 平台"
範圍蔓延	"包含支付、社群、訊息等 10 個功能"	"核心功能不超過 7 個"
目標模糊	"所有人都可以使用"	"25-35 歲的城市白领"

手動修復：

檢查失敗的 PRD：

bash

cat artifacts/_failed/prd/prd.md

修正內容：

刪除技術堆疊描述
精簡功能列表到 ≤ 7 個
補充非目標列表

手動移動到正確位置：

bash

mv artifacts/_failed/prd/prd.md artifacts/prd/prd.md

問題 8：UI 階段失敗

症狀：

頁面數量 > 8（範圍蔓延）
預覽 HTML 檔案損壞
使用 AI 風格（Inter 字型 + 紫色漸層）
YAML 解析失敗

原因：UI 範圍過大或未遵循美學指南。

處理流程：

1. 統計 ui.schema.yaml 中的頁面數量
2. 嘗試在瀏覽器中開啟 preview.web/index.html
3. 驗證 YAML 語法
4. 檢查是否使用禁止的 AI 風格元素

手動修復：

驗證 YAML 語法：

bash

npx js-yaml .factory/artifacts/ui/ui.schema.yaml

在瀏覽器中開啟預覽：

bash

open artifacts/ui/preview.web/index.html  # macOS
xdg-open artifacts/ui/preview.web/index.html  # Linux

精簡頁面數量：檢查 ui.schema.yaml，確保頁面數量 ≤ 8

問題 9：Tech 階段失敗

症狀：

Prisma schema 語法錯誤
引入微服務、快取等過度設計
資料模型過多（表格數量 > 10）
缺少 API 定義

原因：架構複雜化或資料庫設計問題。

處理流程：

1. 執行 npx prisma validate 驗證 schema
2. 檢查 tech.md 是否包含必要章節
3. 統計資料模型數量
4. 檢查是否引入非必要複雜技術

手動修復：

驗證 Prisma Schema：

bash

cd artifacts/backend/
npx prisma validate

簡化架構：檢查 artifacts/tech/tech.md，移除非必要技術（微服務、快取等）
補充 API 定義：確保 tech.md 包含所有必需的 API 端點

問題 10：Code 階段失敗

症狀：

依賴安裝失敗
TypeScript 編譯錯誤
缺少必要檔案
測試失敗
API 無法啟動

原因：依賴版本衝突、類型問題或程式邏輯錯誤。

處理流程：

1. 執行 npm install --dry-run 檢查依賴
2. 執行 npx tsc --noEmit 檢查類型
3. 對照檔案清單檢查目錄結構
4. 執行 npm test 驗證測試
5. 若以上全部通過，嘗試啟動服務

常見依賴問題修復：

bash

# 版本衝突
rm -rf node_modules package-lock.json
npm install

# Prisma 版本不符
npm install @prisma/client@latest prisma@latest

# React Native 依賴問題
npx expo install --fix

TypeScript 錯誤處理：

bash

# 檢查類型錯誤
npx tsc --noEmit

# 修復後重新驗證
npx tsc --noEmit

目錄結構檢查：

確保包含以下必需檔案/目錄：

artifacts/backend/
├── package.json
├── tsconfig.json
├── prisma/
│   ├── schema.prisma
│   └── seed.ts
├── src/
│   ├── index.ts
│   ├── lib/
│   └── routes/
└── vitest.config.ts

artifacts/client/
├── package.json
├── tsconfig.json
├── app.json
└── src/

問題 11：Validation 階段失敗

症狀：

驗證報告不完整
嚴重問題過多（錯誤數 > 10）
安全問題（檢測到硬編碼金鑰）

原因：Code 階段品質差或存在安全問題。

處理流程：

1. 解析 report.md 確認所有章節存在
2. 統計嚴重問題數量
3. 若嚴重問題 > 10，建議回滾到 Code 階段
4. 檢查安全掃描結果

手動修復：

檢視驗證報告：

bash

cat artifacts/validation/report.md

修復嚴重問題：根據報告逐項修復
回滾到 Code 階段（如果問題太多）：

bash

factory run code  # 從 Code 階段重新開始

問題 12：Preview 階段失敗

症狀：

README 不完整（缺少安裝步驟）
Docker 建置失敗
部署設定缺失

原因：內容遺漏或設定問題。

處理流程：

1. 檢查 README.md 包含所有必要章節
2. 嘗試 docker build 驗證 Dockerfile
3. 檢查部署設定檔是否存在

手動修復：

驗證 Docker 設定：

bash

cd artifacts/preview/
docker build -t my-app .

檢查部署檔案：

確保存在以下檔案：

artifacts/preview/
├── README.md
├── Dockerfile
├── docker-compose.yml
└── .github/workflows/ci.yml  # CI/CD 設定

越權錯誤處理

問題 13：Agent 越權寫入

症狀：

bash

Error: Unauthorized write to <path>
Artifacts moved to: artifacts/_untrusted/<stage-id>/
Pipeline paused. Manual intervention required.

原因：Agent 向未授權的目錄或檔案寫入內容。

解決方案：

檢查越權檔案：

bash

ls -la artifacts/_untrusted/<stage-id>/

審查權限矩陣：確認該 Agent 的可寫入範圍
選擇處理方式：
- 方案 A：修正 Agent 行為（推薦）
在 AI 助手中明確指出越權問題，要求修正。
- 方案 B：移動檔案到正確位置（謹慎）
如果你確信檔案應該存在，手動移動：
bash
```
mv artifacts/_untrusted/<stage-id>/<file> artifacts/<target-stage>/
```
- 方案 C：調整權限矩陣（進階）
修改 .factory/policies/capability.matrix.md，增加該 Agent 的寫入權限。
繼續執行：

bash

factory continue

範例場景：

Code Agent 試圖修改 artifacts/prd/prd.md（違反職責邊界）
UI Agent 試圖建立 artifacts/backend/ 目錄（超出權限範圍）
Tech Agent 試圖寫入 artifacts/ui/ 目錄（越界）

分會話執行問題

問題 14：Token 不足或上下文累積

症狀：

AI 回答變慢
上下文過長導致模型效能下降
Token 消耗過大

原因：同一會話中累積了太多對話歷史。

解決方案：使用 factory continue

factory continue 指令允許你：

儲存目前狀態到 .factory/state.json
啟動新的 Claude Code 視窗
從目前階段繼續執行

執行步驟：

檢視目前狀態：

bash

factory status

輸出範例：

bash

Pipeline Status:
───────────────────────────────────────
Project: my-app
Status: Waiting
Current Stage: tech
Completed: bootstrap, prd, ui

在新的會話中繼續：

bash

factory continue

效果：

每個階段獨享乾淨上下文
避免累積 Token
支援中斷恢復

手動啟動新會話（如果 factory continue 失敗）：

bash

# 重新產生權限設定
claude "請重新產生.claude/settings.local.json，允許 Read/Write/Glob/Bash 操作"

# 手動啟動新會話
claude "請繼續執行管線，目前階段是 tech"

環境和權限問題

問題 15：Node.js 版本過低

症狀：

bash

Error: Node.js version must be >= 16.0.0

原因：Node.js 版本不滿足要求。

解決方案：

檢查版本：

bash

node --version

升級 Node.js：

bash

# macOS
brew install node@18
brew link --overwrite node@18

# Linux (使用 nvm)
nvm install 18
nvm use 18

# Windows (從官網下載)
# https://nodejs.org/

問題 16：Claude Code 權限問題

症狀：

AI 提示"沒有讀寫權限"
AI 無法存取 .factory/ 目錄

原因：.claude/settings.local.json 權限設定不正確。

解決方案：

檢查權限檔案：

bash

cat .claude/settings.local.json

重新產生權限：

bash

factory continue  # 自動重新產生

或手動執行：

bash

node -e "
const { generateClaudeSettings } = require('./cli/utils/claude-settings');
generateClaudeSettings(process.cwd());
"

正確權限設定範例：

json

{
  "allowedCommands": ["npm", "npx", "node", "git"],
  "allowedPaths": [
    "/absolute/path/to/project/.factory",
    "/absolute/path/to/project/artifacts",
    "/absolute/path/to/project/input",
    "/absolute/path/to/project/node_modules"
  ]
}

問題 17：網路問題導致依賴安裝失敗

症狀：

bash

Error: Network request failed
npm ERR! code ECONNREFUSED

原因：網路連線問題或 npm 原存取失敗。

解決方案：

檢查網路連線：

bash

ping registry.npmjs.org

切換 npm 原：

bash

# 使用淘寶映像
npm config set registry https://registry.npmmirror.com

# 驗證
npm config get registry

重新安裝依賴：

bash

rm -rf node_modules package-lock.json
npm install

人工介入決策樹

Stage 失敗
    │
    ▼
是否第一次失敗?
    ├─ Yes → 自動重試
    │         │
    │         ▼
    │     重試成功? → Yes → 繼續流程
    │            │
    │            No → 第二次失敗
    │
    └─ No → 分析失敗原因
              │
              ▼
          是輸入問題嗎?
              ├─ Yes → 修改輸入檔案
              │         └─ 回滾到上游 Stage
              │
              └─ No → 請求人工介入

決策要點：

第一次失敗：允許自動重試，觀察錯誤是否消失
第二次失敗：停止自動處理，需要你手動審查
輸入問題：修改 input/idea.md 或上游產物
技術問題：檢查依賴、設定或程式邏輯
越權問題：審查權限矩陣或 Agent 行為

踩坑提醒

❌ 常見錯誤

直接修改上游產物
錯誤做法：在 PRD 階段修改 input/idea.md
正確做法：回滾到 Bootstrap 階段
忽略檢查點確認
錯誤做法：快速跳過所有檢查點
正確做法：仔細檢查每個階段的產物是否符合預期
手動刪除失敗的產物
錯誤做法：刪除 _failed/ 目錄
正確做法：保留失敗的產物用於對比分析
修改後不重新產生權限
錯誤做法：修改專案結構後不更新 .claude/settings.local.json
正確做法：執行 factory continue 自動更新權限

✅ 最佳實踐

早期失敗：盡早發現問題，避免在後續階段浪費時間
詳細日誌：保留完整的錯誤日誌，便於排查問題
原子操作：每個階段的輸出應該是原子的，便於回滾
保留證據：失敗產物歸檔後再重試，便於對比分析
漸進重試：重試時提供更具體的指導，而非簡單重複

本課小結

本課程涵蓋了 AI App Factory 使用過程中的各類常見問題：

類別	問題數	核心解決方法
初始化	3	清理目錄、安裝 AI 助手、手動啟動
管線執行	2	確認專案結構、檢查設定檔
階段失敗	7	重試、回滾、修復後重新執行
越權處理	1	審查權限矩陣、移動檔案或調整權限
分會話執行	1	使用 `factory continue` 啟動新會話
環境權限	3	升級 Node.js、重新產生權限、切換 npm 原

關鍵要點：

每個階段允許自動重試一次
連續失敗兩次後需要人工介入
失敗產物自動歸檔到 _failed/
越權檔案移至 _untrusted/
使用 factory continue 節省 Token

記住：

遇到問題不要慌，先看錯誤日誌，再檢查對應的產物目錄，參考本課程的解決方案逐步排查。大多數問題都可以透過重試、回滾或修復輸入檔案來解決。

下一課預告

下一課我們學習 最佳實踐。
你會學到：
如何提供清晰的產品描述
如何利用檢查點機制
如何控制專案範圍
如何逐步迭代優化

相關閱讀：

失敗處理與回滾 - 深入了解失敗處理策略
權限與安全機制 - 理解能力邊界矩陣
上下文優化 - 節省 Token 的技巧

附錄：原始碼參考

點擊展開查看原始碼位置

更新時間：2026-01-29

功能	檔案路徑	行號
初始化目錄檢查	`cli/commands/init.js`	32-53
AI 助手啟動	`cli/commands/init.js`	119-147
失敗策略定義	`policies/failure.policy.md`	1-276
錯誤碼規範	`policies/error-codes.md`	1-469
能力邊界矩陣	`policies/capability.matrix.md`	1-23
管線設定	`pipeline.yaml`	全文
排程器核心	`agents/orchestrator.checkpoint.md`	1-301
Continue 指令	`cli/commands/continue.js`	1-144

關鍵常數：

允許的 Must Have 功能數量：≤ 7
允許的 UI 頁面數量：≤ 8
允許的資料模型數量：≤ 10
重試次數：每個階段允許重試一次

關鍵函數：

isFactoryProject(dir) - 檢查是否為 Factory 專案
isDirectorySafeToInit(dir) - 檢查目錄是否可初始化
generateClaudeSettings(projectDir) - 產生 Claude Code 權限設定
factory continue - 在新會話中繼續執行管線

常見問題與故障排除 ​

學完你能做什麼 ​

你現在的困境 ​

🎒 開始前的準備 ​

核心思路 ​

失敗處理的三個層次 ​

越權處理規則 ​

權限邊界 ​

初始化問題 ​

問題 1：目錄非空錯誤 ​

問題 2：已存在 Factory 專案 ​

問題 3：AI 助手啟動失敗 ​

管線執行問題 ​

問題 4：非專案目錄錯誤 ​

問題 5：Pipeline 檔案未找到 ​

階段失敗處理 ​

問題 6：Bootstrap 階段失敗 ​

問題 7：PRD 階段失敗 ​

問題 8：UI 階段失敗 ​

問題 9：Tech 階段失敗 ​

問題 10：Code 階段失敗 ​

問題 11：Validation 階段失敗 ​

問題 12：Preview 階段失敗 ​

越權錯誤處理 ​

問題 13：Agent 越權寫入 ​

分會話執行問題 ​

問題 14：Token 不足或上下文累積 ​

環境和權限問題 ​

問題 15：Node.js 版本過低 ​

問題 16：Claude Code 權限問題 ​

問題 17：網路問題導致依賴安裝失敗 ​

人工介入決策樹 ​

踩坑提醒 ​

❌ 常見錯誤 ​

✅ 最佳實踐 ​

本課小結 ​

下一課預告 ​

附錄：原始碼參考 ​

常見問題與故障排除

學完你能做什麼

你現在的困境

🎒 開始前的準備

核心思路

失敗處理的三個層次

越權處理規則

權限邊界

初始化問題

問題 1：目錄非空錯誤

問題 2：已存在 Factory 專案

問題 3：AI 助手啟動失敗

管線執行問題

問題 4：非專案目錄錯誤

問題 5：Pipeline 檔案未找到

階段失敗處理

問題 6：Bootstrap 階段失敗

問題 7：PRD 階段失敗

問題 8：UI 階段失敗

問題 9：Tech 階段失敗

問題 10：Code 階段失敗

問題 11：Validation 階段失敗

問題 12：Preview 階段失敗

越權錯誤處理

問題 13：Agent 越權寫入

分會話執行問題

問題 14：Token 不足或上下文累積

環境和權限問題

問題 15：Node.js 版本過低

問題 16：Claude Code 權限問題

問題 17：網路問題導致依賴安裝失敗

人工介入決策樹

踩坑提醒

❌ 常見錯誤

✅ 最佳實踐

本課小結

下一課預告

附錄：原始碼參考