# CLAUDE.md - AI 夜間開發系統開發指南

## 專案概述

這是一個 AI 夜間持續開發系統，透過 Cron Job 每隔 20 分鐘自動執行 AI 開發任務。系統包含 Web 介面管控和完整的日誌追蹤功能。

## 系統架構

### 核心元件
- **主控腳本**: `ai-dev-loop.sh` - 執行 AI 開發任務的核心引擎
- **控制面板**: `ai-dev-control.sh` - 系統管理命令介面
- **Web 服務**: `web_server.py` + `dashboard.html` - FastAPI Web 控制台
- **資料庫**: `db_manager.py` - SQLite 資料庫管理
- **專案配置**: `projects.yml` - YAML 專案配置檔案
- **配置載入器**: `load_project_config.py` - Python 配置解析器
- **安裝工具**: `setup.sh`, `install-cron.sh`, `project-configs.sh`

### 技術棧
- **Shell Scripts**: Bash 4.0+ (核心邏輯)
- **Python**: FastAPI + Uvicorn (Web 服務)
- **前端**: HTML5 + JavaScript (Web Dashboard)
- **資料庫**: SQLite3 (日誌和配置存儲)
- **系統服務**: Cron (定時執行)

## 開發環境設置

### 必要依賴
```bash
# 檢查系統需求
bash --version  # 需要 4.0+
git --version
python3 --version  # 需要 3.8+
crontab -l  # 檢查 cron 可用性

# 安裝 Python 依賴
pip install -r requirements.txt
```

### 專案結構
```
ai-night-dev-system/
├── setup.sh                 # 一鍵安裝腳本
├── ai-dev-control.sh        # 主控制面板
├── ai-dev-loop.sh           # 核心執行引擎
├── web-control.sh           # Web 服務管理
├── start-web.sh             # Web 服務啟動器
├── web_server.py            # FastAPI 服務端
├── dashboard.html           # Web 控制台前端
├── db_manager.py            # 資料庫管理器
├── install-cron.sh          # Cron 安裝工具
├── projects.yml             # 專案配置檔案（YAML）
├── load_project_config.py   # 專案配置載入器
├── project-configs.sh       # 專案配置管理（Shell 包裝）
├── test.sh                  # 系統測試腳本
├── requirements.txt         # Python 依賴
├── README.md                # 完整說明文件
└── docs/
    ├── INDEX.md             # 檔案索引
    ├── QUICKSTART.md        # 快速入門指南
    ├── ARCHITECTURE.md      # 架構說明
    └── prompt-examples.md   # Prompt 範例
```

## 開發工作流程

### 新功能開發
1. **分析需求**: 先讀 INDEX.md 了解現有架構
2. **選擇元件**: 確定要修改的腳本或檔案
3. **備份測試**: 使用 `./test.sh` 確認系統狀態
4. **開發修改**: 遵循現有 coding style
5. **測試驗證**: 再次執行 `./test.sh`
6. **文件更新**: 更新相關 .md 文件

### 代碼風格
- **Shell Scripts**: 使用 bash shebang, 4 空格縮進
- **Python**: 遵循 PEP 8, 使用 type hints
- **命名規範**: snake_case (Python), kebab-case (shell files)
- **錯誤處理**: `set -e` (shell), try/except (Python)

### 常用開發命令
```bash
# 系統測試
./test.sh

# 查看系統狀態
./ai-dev-control.sh status

# 啟動 Web 服務 (開發模式)
./web-control.sh start

# 查看 Web 服務日誌
./web-control.sh logs

# 執行單次開發循環
./ai-dev-control.sh run

# 查看執行日誌
./ai-dev-control.sh logs latest
```

## 重要檔案說明

### ai-dev-loop.sh
**功能**: 系統核心，執行 AI 開發任務
**位置**: `ai-dev-loop.sh:1`
**關鍵流程**:
1. 載入環境配置 (`~/.ai-dev-env`)
2. 讀取專案 prompt (`.ai-dev-prompt.txt`)
3. 呼叫 AI CLI (claude/copilot/gemini)
4. 處理 AI 輸出並 commit 變更
5. 記錄執行日誌

### web_server.py
**功能**: FastAPI Web 控制台後端
**位置**: `web_server.py:1`
**主要端點**:
- `/` - Web Dashboard
- `/api/status` - 系統狀態
- `/api/projects` - 專案管理
- `/api/logs` - 日誌查詢

### ai-dev-control.sh
**功能**: 系統控制面板
**位置**: `ai-dev-control.sh:1`
**主要命令**:
- `start <project>` - 啟動專案
- `stop` - 停止系統
- `status` - 查看狀態
- `run` - 立即執行一次

## 測試指南

### 自動測試
```bash
# 完整系統測試
./test.sh

# Web 服務測試
curl http://localhost:8000/api/health
```

### 手動測試
1. **功能測試**: 啟動專案並執行一次循環
2. **Web 介面測試**: 訪問 Dashboard 確認功能正常
3. **Cron 測試**: 檢查定時任務是否正確安裝
4. **日誌測試**: 確認日誌正確記錄

## 故障排除

### 常見問題
1. **Cron 未執行**: 檢查 `crontab -l`, 重新安裝 `./install-cron.sh`
2. **AI CLI 錯誤**: 檢查 API Key 設置和網路連線
3. **權限問題**: 確認所有 .sh 檔案有執行權限
4. **Web 服務啟動失敗**: 檢查 port 8000 是否被佔用

### 日誌位置
- **系統日誌**: `~/.ai-dev-logs/`
- **Web 服務日誌**: `/tmp/ai-dev-system-web.log`
- **Cron 日誌**: `/var/log/cron` (需要 sudo)

## 部署注意事項

### 環境變數配置
在 `~/.ai-dev-env` 中設置:
```bash
export AI_DEV_PROJECT="your-project"
export AI_DEV_PROJECT_DIR="/path/to/project"
export AI_DEV_AI_PROVIDER="claude"  # 或 copilot, gemini
export AI_DEV_ENABLE="true"
export ANTHROPIC_API_KEY="your-key"
```

### 安全考量
- API Key 不存儲在檔案中，使用環境變數
- Git 提交只在本地，不自動推送
- Web 服務預設只綁定 localhost
- 所有腳本檔案權限設為 755

### 效能優化
- 每次執行間隔 20 分鐘，避免 API 限制
- 日誌自動輪轉，避免檔案過大
- SQLite 資料庫定期清理舊記錄

## 擴展指南

### 新增 AI Provider
1. 修改 `ai-dev-loop.sh` 新增 provider 邏輯
2. 在 `projects.yml` 中設定專案的 `ai_provider` 欄位
3. 修改 Web 介面 provider 選項

### 新增專案範本
1. 編輯 `projects.yml` 新增專案配置區塊：
   ```yaml
   new-project:
     name: "新專案名稱"
     project_dir: "$HOME/projects/new-project"
     ai_provider: "claude"
     enable: true
     log_dir: "$HOME/.ai-dev-logs"
     max_iterations: 30
     description: "專案描述"
   ```
2. （可選）在 `project-configs.sh` 新增便捷函數 `export_newproject_config()`
3. 在 `prompt-examples.md` 新增範例 prompt
4. 更新文件說明新專案類型

### 管理專案配置
使用 `load_project_config.py` 管理專案：
```bash
# 列出所有專案
python3 load_project_config.py list

# 查看專案資訊
python3 load_project_config.py info <project-id>

# 在 shell 中載入專案配置
source project-configs.sh
load_project_config <project-id>

# 或使用預定義函數
export_sdd_config
export_wedding_config
```

### 新增 Web 功能
1. 在 `web_server.py` 新增 API 端點
2. 修改 `dashboard.html` 新增前端介面
3. 更新 `db_manager.py` 如需資料庫變更

## Git 工作流程

### 提交慣例
- feat: 新功能
- fix: 修復錯誤
- docs: 文件更新
- style: 代碼格式
- refactor: 重構代碼
- test: 測試相關

### 分支策略
- `main`: 穩定版本
- `develop`: 開發版本
- `feature/*`: 功能分支

## 聯絡資訊

此系統設計為自動化開發工具，如有問題可查閱:
1. `./test.sh` 診斷
2. `README.md` 詳細文件
3. `QUICKSTART.md` 快速解決方案

**最後更新**: 2026-01-04
**版本**: 1.0
**授權**: MIT License