name: code-factory description: "自動生成完整專案結構(README+requirements+test+ASSET_MANIFEST)，執行測試驗證後才交付" allowed-tools: - read - write - edit - exec - apply_patch

Code Factory — 程式碼交付工廠 Skill (v1.0)

將自然語言需求自動轉化為可交付的完整專案資產。

架構：分層模組化設計，狀態機驅動 + 契約校驗 + 事務保護 + 熔斷容錯。

觸發方式

自動觸發條件

當檢測到使用者請求生成完整專案/工具/應用時自動啟用。

架構概覽

使用者輸入
  │
  ▼
┌──────────────────────────────────────────────┐
│  contracts/    資料契約層                     │
│  ├─ input_schema.py    → ProjectRequest      │
│  ├─ output_schema.py   → ProjectResult       │
│  ├─ step_context.py    → StepContext         │
│  ├─ step_outputs.py    → TypedDict 型別定義   │
│  ├─ asset_manifest_schema.py                 │
│  └─ exceptions.py      → 統一異常定義         │
└──────────────────────────────────────────────┘
  │
  ▼
┌──────────────────────────────────────────────┐
│  layers/                     核心執行層         │
│  ├─ orchestrator.py           狀態機編排引擎    │
│  ├─ step_registry.py          步驟登錄檔        │
│  ├─ step_handlers/            步驟處理器 (7個)  │
│  │   ├─ preflight_handler.py                   │
│  │   ├─ snapshot_handler.py                    │
│  │   ├─ spec_handler.py                        │
│  │   ├─ asset_handler.py                       │
│  │   ├─ verify_handler.py                      │
│  │   ├─ retry_handler.py                       │
│  │   └─ delivery_handler.py                    │
│  ├─ preflight.py              Phase 0 預檢     │
│  ├─ spec_engine.py            Spec 推導引擎    │
│  ├─ asset_generator.py        資產生成器       │
│  ├─ verifier.py               自動驗證器       │
│  ├─ retry_controller.py       智慧重試控制器    │
│  └─ deliverer.py              交付組裝器       │
│  Phase0 → Step1 → Step2 → ... → Step6          │
│  每步獨立執行、獨立失敗、獨立回滾               │
└─────────────────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────┐
│  middlewares/ 橫切中介軟體                         │
│  ├─ circuit_breaker.py      熔斷器              │
│  ├─ transaction_manager.py  事務管理 (UoW)       │
│  ├─ anti_corruption.py      防腐層 (ACL)         │
│  ├─ pipeline_guard.py       管道守護者           │
│  ├─ saga_coordinator.py     Saga 補償協調器      │
│  ├─ side_effect_log.py      副作用追蹤器         │
│  └─ service_container.py    DI 容器              │
└─────────────────────────────────────────────────┘

執行流程

Phase 0: Preflight — 環境預檢

實現模組: layers/preflight.py

生成前先驗證環境完整性，避免生成後跑不通： 1. 檢查 Python 版本是否滿足專案需求 2. 檢查目標目錄是否存在、可寫 3. 檢查必要依賴是否已安裝 4. 檢查磁碟空間是否充足（≥100MB） 5. 不通過則直接報告缺少什麼，後續步驟全部 SKIPPED

Step 1: 環境快照

實現模組: layers/step_handlers/snapshot_handler.py

結構化採集環境資訊，經過 anti_corruption.py 校驗後存入 StepContext。

Step 2: Spec 推導與計劃生成

實現模組: layers/spec_engine.py

根據使用者需求推導內部規格（spec），輸出格式受 contracts/ Schema 約束： 1. Spec 推導：從使用者需求中提取功能範圍、輸入輸出、邊界條件、驗收標準 2. 驗收標準格式：每條用 Given/When/Then + P1/P2/P3 優先順序標記 3. 使用者完全無感知——不要求使用者寫任何 spec，AI 內部完成

Step 3: 生成資產檔案

實現模組: layers/asset_generator.py + templates/

所有檔案寫入通過 TransactionManager 暫存到 staging 區域： - 驗證全部通過 → tx.commit() 原子提交 - 任何步驟失敗 → tx.rollback() 完整回滾

標準化專案結構：

project_assets/[project_name]/
├── src/                        # 原始碼目錄
│   └── main.py                 # 主程式（<!-- HARD-GATE --> 標記）
├── tests/                      # 測試目錄
│   └── test_main.py            # pytest 測試
├── docs/                       # 文件目錄
│   └── README.md               # 使用說明/安裝/依賴
├── requirements.txt            # 依賴清單
├── run.sh                      # 一鍵執行指令碼
├── SKILL.md                     # AI 技能後設資料頭
├── ASSET_MANIFEST.md           # 人類可讀版資源地圖表
├── manifest.json               # 機器可讀版資產清單
└── environment.toml             # 環境隔離配置

Step 4: 自動驗證（含依賴圖譜檢查）

實現模組: layers/verifier.py

1. 依賴影響預檢：分析模組間依賴，檢查是否有迴圈引用
2. HARD-GATE 強制門禁驗證：凡標記 <!-- HARD-GATE --> 的關鍵函式/API，必須通過獨立驗證
3. 執行 pytest tests/ -v → 確認全部測試通過
4. 輸出結構化審查報告（Risk Assessment → 逐個檔案 → 缺失測試 → 建議）

Step 5: 智慧重試

實現模組: layers/retry_controller.py

受 circuit_breaker.py 熔斷器保護： - 第 1 次失敗：自動分析錯誤→修改程式碼→重新驗證 - 第 2 次失敗：更換修復策略（縮小修改範圍）→重新驗證 - 第 3 次失敗：記錄結構化失敗模式到 learnings/failure_patterns.json → 暫停並報告

Step 6: 交付

實現模組: layers/deliverer.py

輸出： - 專案路徑（絕對路徑） - README.md 內容預覽 - ASSET_MANIFEST.md 資源地圖摘要 - manifest.json 機器可讀摘要 - 測試結果摘要

狀態機定義

PENDING ──→ RUNNING ──→ SUCCESS
                    ├──→ FAILED ──→ (retry ≤ 3) ──→ RUNNING
                    │         └──→ (retry exhausted) ──→ 記錄失敗模式
                    ├──→ TIMED_OUT (單步驟 > 120s)
                    └──→ ROLLED_BACK (事務回滾)
PENDING ──→ SKIPPED (前置條件不滿足，如 Phase 0 失敗)

全域性熔斷規則 (middlewares/circuit_breaker.py)： - 全域性超時：600s - 單步驟超時：120s - 連續 3 次失敗 → 熔斷開啟，拒絕後續請求

資料契約（見 contracts/ 目錄）

程式碼規範（強制）

1. 簡潔優先：10行能解決→不寫20行
2. 單一職責：每個函式≤30行，只做一件事
3. 命名清晰：不用 x/tmp/data 等無意義變數名
4. 型別提示：所有函式引數+返回值加 type hints
5. 錯誤處理：不用 pass 或裸 except
6. 零硬編碼：魔法數字/路徑/配置提取為常量或引數
7. 無除錯print：最終程式碼不含 print，用正式日誌或異常
8. HARD-GATE 強制門禁：關鍵函式/API 入口前必須插入 <!-- HARD-GATE --> 註釋標記
9. 每個公開函式≥1個測試用例
10. 必須包含邊界條件測試（空列表/零值/檔案不存在）

注意事項

發現更多技能外掛，請訪問7w4.net。

• 所有檔案使用 UTF-8 編碼
• 如果使用者指定了專案名以外的路徑偏好，使用使用者指定路徑
• 不要修改專案目錄以外的任何檔案
• 如果使用者只說了功能沒給專案名，用功能名加小寫下劃線命名
• 技能自身的測試位於 tests/ 目錄，執行 pytest tests/ -v

執行技能自身測試

pip install -e ".[dev]"
pytest tests/ -v

✅ 自檢清單

Agent 執行指令

職責邊界

標準工作流

1. 接收任務描述 -> 建立專案目錄
2. Agent 執行 Spec 推導
3. Agent 生成程式碼檔案
4. 安裝依賴: pip install -e .
5. 執行測試: pytest tests/ -v
6. GREEN -> 交付; RED -> 分析報告->修復->重測(最多3輪)
7. 寫入交付物

錯誤恢復

• pip失敗 -> 檢查 requirements.txt 格式
• pytest失敗 -> 讀取錯誤資訊，定位失敗用例
• 3輪重試仍失敗 -> 記錄失敗模式，暫停報告

這個 Skill 質量相當不錯，架構設計專業嚴謹。它能自動把需求變成完整的專案程式碼，包括測試、文件、依賴配置等，還會在交付前自動跑測試驗證。安全性方面也考慮周全，有輸入校驗和檔案操作保護。優點是功能完善、流程規範、容錯能力強；不足是部分功能（如失敗模式學習）還是空的，版本號標識有混亂。適合對程式碼質量有要求的開發者使用。