claude-coder 1.6.2 → 1.7.0

package/{templates → prompts}/SCAN_PROTOCOL.md

@@ -1,123 +1,118 @@
-<!-- 
-  Scan Protocol for Claude Coder.
-  Only injected during scan sessions — not used in coding sessions.
-  Contains: scan steps, project_profile.json format.
--->
-
-# 项目扫描协议（首次运行时执行）
-
-当 `project_profile.json` 不存在时，按以下步骤扫描项目并生成配置文件。
-
-## 步骤 1：判断项目类型
-
-检查项目根目录：
-- 如果存在代码文件（`.py`, `.js`, `.ts`, `package.json`, `requirements.txt` 等）→ **旧项目**（已有代码）
-- 如果根目录几乎为空（仅有 `.claude-coder/` 和少量文件）→ **新项目**（从零开始）
-
-## 步骤 2A：旧项目 — 扫描现有代码，**优先整理文档**
-
-**文档先行**：旧项目在扫描前，必须先确保项目文档可读、可用。文档是后续 session 高质量执行的基础 — AI Agent 会在每次编码前读取文档来了解架构和接口约定。
-
-**文档标准（按优先级）**：
-1. **README.md**（必须有）：项目简介、技术栈、目录结构、如何运行。若缺失或过于简略，先补充
-2. **`.claude/CLAUDE.md`**（推荐有）：检查 `.claude/` 目录下是否已有 `CLAUDE.md`。若无，生成一份项目指令文件，采用 WHAT/WHY/HOW 格式：WHAT（项目是什么、技术栈）、WHY（关键技术决策）、HOW（开发命令、测试命令、关键路径表、编码规则）。此文件会被 Claude Code 自动加载为项目上下文
-3. **API 文档**：如果项目有 API 且无文档，在 `.claude/CLAUDE.md` 的 HOW 部分或 README 中补充主要端点列表
-
-按顺序检查以下文件，**存在则读取**，不存在则跳过：
-
-1. `package.json` → Node.js 项目，读取 dependencies 判断框架（React/Vue/Express 等）
-2. `pyproject.toml` / `requirements.txt` / `setup.py` / `setup.cfg` → Python 项目，判断框架（FastAPI/Django/Flask 等）
-3. `Cargo.toml` → Rust，`go.mod` → Go，`pom.xml` / `build.gradle` → Java
-4. `docker-compose.yml` / `Dockerfile` → 容器化配置，提取服务定义
-5. `Makefile` → 构建方式
-6. `README.md` / `docs/` → 现有文档（若缺失或过简，**先整理再扫描**；在 session_result.json 的 notes 中记录文档状态）
-7. `.env` / `.env.example` → 环境变量配置
-8. 运行 `ls` 查看顶层目录结构
-
-根据扫描结果，生成 `.claude-coder/project_profile.json`（格式见下方）。若项目有自定义初始化步骤（如 `python manage.py migrate`），填充 `custom_init` 字段。`existing_docs` 须如实列出项目中**所有**可读文档路径（包括本次扫描中新生成的文档）。
-
-## 步骤 2B：新项目 — 脚手架搭建
-
-1. **优先检查项目根目录是否存在 `requirements.md`**，如果存在，以其中的技术约束和设计要求为准
-2. 根据需求（`requirements.md` 或 harness 传入的需求文本），设计技术架构
-3. 创建项目目录结构和基础文件（入口文件、配置文件、依赖文件等）
-4. 生成 `README.md`（项目用途、技术栈、如何运行）
-5. 如果 `.claude/CLAUDE.md` 不存在，生成项目指令文件（WHAT/WHY/HOW 格式），包含模块职责、数据流、API 路由、开发和测试命令
-6. 初始化包管理（`npm init` / `pip freeze` 等）
-7. 完成后，执行**步骤 2A 的扫描流程**生成 `project_profile.json`
-
-## 步骤 3：生成 tasks.json
-
-根据用户需求和 user prompt 中的「任务分解指导」，将功能分解为任务。
-格式参见 CLAUDE.md 中的 tasks.json 章节。
-
-## 步骤 4：收尾
-
-1. 写入 `.claude-coder/session_result.json`（notes 中记录初始化摘要）
-3. `git add -A && git commit -m "init: 项目扫描 + 任务分解"`
-
----
-
-## project_profile.json 格式
-
-```json
-{
-  "name": "项目名称（从 package.json 或目录名自动检测）",
-  "detected_at": "2026-02-13T10:00:00",
-  "project_type": "existing | new",
-  "tech_stack": {
-    "languages": ["python", "typescript"],
-    "backend": {
-      "framework": "fastapi | django | express | none",
-      "runtime": "uvicorn | gunicorn | node | none",
-      "entry": "main:app | app.py | index.js"
-    },
-    "frontend": {
-      "framework": "react | vue | none",
-      "bundler": "vite | webpack | none",
-      "dir": "web | frontend | client | ."
-    },
-    "database": "mongodb | postgresql | sqlite | none",
-    "package_managers": ["pip", "npm", "cargo"]
-  },
-  "services": [
-    {
-      "name": "backend",
-      "command": "启动命令",
-      "port": 8000,
-      "health_check": "http://localhost:8000/health",
-      "cwd": "."
-    },
-    {
-      "name": "frontend",
-      "command": "npm run dev",
-      "port": 5173,
-      "health_check": "http://localhost:5173",
-      "cwd": "web"
-    }
-  ],
-  "env_setup": {
-    "python_env": "conda:env_name | venv | system",
-    "node_version": "20 | 18 | none"
-  },
-  "existing_docs": ["README.md", ".claude/CLAUDE.md"],
-  "has_tests": false,
-  "has_docker": false,
-  "mcp_tools": {
-    "playwright": false
-  },
-  "custom_init": ["python manage.py migrate"],
-  "scan_files_checked": [
-    "package.json", "pyproject.toml", "requirements.txt",
-    "Dockerfile", "docker-compose.yml", "Makefile", "README.md"
-  ]
-}
-```
-
-**注意**：
-- `existing_docs`：列出项目中所有可读文档路径，Agent 实现前按需读取与任务相关的文档；扫描时须如实填写全部文档
-- 字段值必须基于实际扫描结果，**禁止猜测**
-- 如果某个字段无法确定，使用 `"none"` 或空数组 `[]`
-- `services` 中的 `command` 必须来自实际的配置文件（package.json scripts、Procfile 等）或标准命令
-- `mcp_tools` 字段：检查 `.claude-coder/.env` 中的 `MCP_PLAYWRIGHT` 等变量。如果 `.env` 不存在，则全部设为 `false`
-- `custom_init`：可选，数组格式。若项目需要额外的初始化命令（如数据库迁移、静态文件收集等），按执行顺序列出。无额外步骤则填 `[]` 或省略
+<!-- 
+  Scan Protocol for Claude Coder.
+  Only injected during scan sessions — not used in coding sessions.
+  Contains: scan steps, project_profile.json format.
+-->
+
+# 项目扫描协议（首次运行时执行）
+
+当 `project_profile.json` 不存在时，按以下步骤扫描项目并生成配置文件。
+
+## 步骤 1：判断项目类型
+
+检查项目根目录：
+- 如果存在代码文件（`.py`, `.js`, `.ts`, `package.json`, `requirements.txt` 等）→ **旧项目**（已有代码）
+- 如果根目录几乎为空（仅有 `.claude-coder/` 和少量文件）→ **新项目**（从零开始）
+
+## 步骤 2A：旧项目 — 扫描现有代码，**优先整理文档**
+
+**文档先行**：旧项目在扫描前，必须先确保项目文档可读、可用。文档是后续 session 高质量执行的基础 — AI Agent 会在每次编码前读取文档来了解架构和接口约定。
+
+**文档标准（按优先级）**：
+1. **README.md**（必须有）：项目简介、技术栈、目录结构、如何运行。若缺失或过于简略，先补充
+2. **`.claude/CLAUDE.md`**（推荐有）：检查 `.claude/` 目录下是否已有 `CLAUDE.md`。若无，生成一份项目指令文件，采用 WHAT/WHY/HOW 格式：WHAT（项目是什么、技术栈）、WHY（关键技术决策）、HOW（开发命令、测试命令、关键路径表、编码规则）。此文件会被 Claude Code 自动加载为项目上下文
+3. **API 文档**：如果项目有 API 且无文档，在 `.claude/CLAUDE.md` 的 HOW 部分或 README 中补充主要端点列表
+
+按顺序检查以下文件，**存在则读取**，不存在则跳过：
+
+1. `package.json` → Node.js 项目，读取 dependencies 判断框架（React/Vue/Express 等）
+2. `pyproject.toml` / `requirements.txt` / `setup.py` / `setup.cfg` → Python 项目，判断框架（FastAPI/Django/Flask 等）
+3. `Cargo.toml` → Rust，`go.mod` → Go，`pom.xml` / `build.gradle` → Java
+4. `docker-compose.yml` / `Dockerfile` → 容器化配置，提取服务定义
+5. `Makefile` → 构建方式
+6. `README.md` / `docs/` → 现有文档（若缺失或过简，**先整理再扫描**；在 session_result.json 的 notes 中记录文档状态）
+7. `.env` / `.env.example` → 环境变量配置
+8. 运行 `ls` 查看顶层目录结构
+
+根据扫描结果，生成 `.claude-coder/project_profile.json`（格式见下方）。若项目有自定义初始化步骤（如 `python manage.py migrate`），填充 `custom_init` 字段。`existing_docs` 须如实列出项目中**所有**可读文档路径（包括本次扫描中新生成的文档）。
+
+## 步骤 2B：新项目 — 脚手架搭建
+
+1. **优先检查项目根目录是否存在 `requirements.md`**，如果存在，以其中的技术约束和设计要求为准
+2. 根据需求（`requirements.md` 或 harness 传入的需求文本），设计技术架构
+3. 创建项目目录结构和基础文件（入口文件、配置文件、依赖文件等）
+4. 生成 `README.md`（项目用途、技术栈、如何运行）
+5. 如果 `.claude/CLAUDE.md` 不存在，生成项目指令文件（WHAT/WHY/HOW 格式），包含模块职责、数据流、API 路由、开发和测试命令
+6. 初始化包管理（`npm init` / `pip freeze` 等）
+7. 完成后，执行**步骤 2A 的扫描流程**生成 `project_profile.json`
+
+## 步骤 3：收尾
+
+1. 写入 `.claude-coder/session_result.json`（notes 中记录扫描摘要：项目类型、技术栈、服务列表）
+2. `git add -A && git commit -m "init: 项目扫描"`
+
+---
+
+## project_profile.json 格式
+
+```json
+{
+  "name": "项目名称（从 package.json 或目录名自动检测）",
+  "detected_at": "2026-02-13T10:00:00",
+  "project_type": "existing | new",
+  "tech_stack": {
+    "languages": ["python", "typescript"],
+    "backend": {
+      "framework": "fastapi | django | express | none",
+      "runtime": "uvicorn | gunicorn | node | none",
+      "entry": "main:app | app.py | index.js"
+    },
+    "frontend": {
+      "framework": "react | vue | none",
+      "bundler": "vite | webpack | none",
+      "dir": "web | frontend | client | ."
+    },
+    "database": "mongodb | postgresql | sqlite | none",
+    "package_managers": ["pip", "npm", "cargo"]
+  },
+  "services": [
+    {
+      "name": "backend",
+      "command": "启动命令",
+      "port": 8000,
+      "health_check": "http://localhost:8000/health",
+      "cwd": "."
+    },
+    {
+      "name": "frontend",
+      "command": "npm run dev",
+      "port": 5173,
+      "health_check": "http://localhost:5173",
+      "cwd": "web"
+    }
+  ],
+  "env_setup": {
+    "python_env": "conda:env_name | venv | system",
+    "node_version": "20 | 18 | none"
+  },
+  "existing_docs": ["README.md", ".claude/CLAUDE.md"],
+  "has_tests": false,
+  "has_docker": false,
+  "mcp_tools": {
+    "playwright": false
+  },
+  "custom_init": ["python manage.py migrate"],
+  "scan_files_checked": [
+    "package.json", "pyproject.toml", "requirements.txt",
+    "Dockerfile", "docker-compose.yml", "Makefile", "README.md"
+  ]
+}
+```
+
+**注意**：
+- `existing_docs`：列出项目中所有可读文档路径，Agent 实现前按需读取与任务相关的文档；扫描时须如实填写全部文档
+- 字段值必须基于实际扫描结果，**禁止猜测**
+- 如果某个字段无法确定，使用 `"none"` 或空数组 `[]`
+- `services` 中的 `command` 必须来自实际的配置文件（package.json scripts、Procfile 等）或标准命令
+- `mcp_tools` 字段：检查 `.claude-coder/.env` 中的 `MCP_PLAYWRIGHT` 等变量。如果 `.env` 不存在，则全部设为 `false`
+- `custom_init`：可选，数组格式。若项目需要额外的初始化命令（如数据库迁移、静态文件收集等），按执行顺序列出。无额外步骤则填 `[]` 或省略

package/prompts/add_user.md

@@ -0,0 +1,24 @@
+你是资深需求分析师，擅长将模糊需求分解为可执行的原子任务。
+这是任务追加 session，不是编码 session。你只分解任务，不实现代码。
+
+{{profileContext}}
+{{taskContext}}
+{{recentExamples}}
+项目绝对路径: {{projectRoot}}
+
+执行步骤（按顺序，不可跳过）：
+1. 读取 .claude-coder/tasks.json 和 .claude-coder/project_profile.json，全面了解项目现状
+2. 分析用户指令：识别核心功能点，判断是单任务还是需要拆分为多任务
+3. 检查重复：对比已有任务，避免功能重叠
+4. 确定依赖：新任务的 depends_on 引用已有或新增任务的 id，形成 DAG
+5. 分解任务：按下方任务分解指南的规则，每个任务独立可测试
+6. 追加到 tasks.json，id 和 priority 从已有最大值递增，status: pending
+7. git add -A && git commit -m "chore: add new tasks"
+8. 写入 session_result.json（格式：{ "session_result": "success", "status_before": "N/A", "status_after": "N/A", "notes": "追加了 N 个任务：简述" }）
+
+{{addGuide}}
+
+{{testRuleHint}}
+不修改已有任务，不实现代码。
+
+用户指令：{{instruction}}

package/prompts/coding_user.md

@@ -0,0 +1,23 @@
+Session {{sessionNum}}。执行 6 步流程。
+效率要求：先规划后编码，完成全部编码后再统一测试，禁止编码-测试反复跳转。后端任务用 curl 验证，不启动浏览器。
+{{mcpHint}}
+{{testHint}}
+{{docsHint}}
+{{envHint}}
+{{taskHint}}
+{{testEnvHint}}
+{{playwrightAuthHint}}
+{{memoryHint}}
+{{serviceHint}}
+
+可用工具与使用规范（严格遵守）：
+- 搜索文件名: Glob（如 **/*.ts），禁止 bash find
+- 搜索文件内容: Grep（正则，基于 ripgrep），禁止 bash grep
+- 读文件: Read（支持批量多文件同时读取），禁止 bash cat/head/tail
+- 列目录: LS，禁止 bash ls
+- 编辑文件: 同一文件多处修改用 MultiEdit（一次原子调用），单处用 Edit
+- 复杂搜索: Task（启动子 Agent 并行搜索，不消耗主 context），适合开放式探索
+- 查文档/API: WebSearch + WebFetch
+- 效率: 多个 Read/Glob/Grep 尽量合并为一次批量调用，减少工具轮次
+
+完成后写入 session_result.json。{{retryContext}}

package/prompts/scan_user.md

@@ -0,0 +1,17 @@
+你是项目初始化 Agent。你的职责是扫描项目并生成 project_profile.json，不分解任务。
+
+项目类型: {{projectType}}
+{{requirement}}
+
+按「项目扫描协议」（SCAN_PROTOCOL.md）执行步骤 1-3：
+1. 判断项目类型（新项目 / 旧项目）
+2. 扫描项目（旧项目扫描代码和文档 / 新项目搭建脚手架）
+3. 收尾：写入 session_result.json 并 git commit
+
+profile 质量要求（必须遵守，harness 会校验）：
+- services 数组必须包含所有可启动服务（command、port、health_check），不得为空
+- existing_docs 必须列出所有实际存在的文档路径
+- 检查 .claude/CLAUDE.md 是否存在，若无则生成（WHAT/WHY/HOW 格式：技术栈、关键决策、开发命令、关键路径、编码规则），并加入 existing_docs
+- scan_files_checked 必须列出所有实际扫描过的文件
+
+注意：本次只扫描项目，不分解任务。任务分解将在后续步骤由 harness 自动调用 add 完成。