# Python Harness 模板生成计划

## 背景

基于 learn-harness-engineering 课程的 harness 五要素体系（指令、工具、环境、状态、反馈），结合 meeting 项目的实际 Claude Code 配置经验，创建一个可复用的 Python 项目 harness 模板。模板分三个层级，用户可按项目复杂度自由选择。

## 输出位置

```
/root/projects/learn-harness-engineering/templates/
├── core/           # 核心精简版
├── standard/       # 完整版
└── full/           # 全功能版
```

每个目录是**完全自包含**的，可以直接 `cp -r` 到新项目使用。

---

## 第一层：core/（核心精简版 — 4 个核心文件）

适用场景：小型脚本、工具项目、快速原型

```
core/
├── CLAUDE.md              # 根指令文件
├── feature_list.json      # 机器可读的功能状态
├── init.sh                # 标准启动脚本
└── claude-progress.md     # 会话进度日志
```

### core/CLAUDE.md
- 融合课程 CLAUDE.md 模板 + meeting 项目的工作流
- 包含：
  - **启动循环**：pwd → 读 progress → 读 feature_list → git log → init.sh → 基线验证
  - **Python 标准**：类型注解必须、Pydantic 数据校验、pathlib、Google 风格 docstring
  - **TDD 工作流**：先写测试后实现，pytest 为默认框架
  - **Human-in-the-Loop 协议**：>20 行代码变更后自动执行自我解释 + 结构检查 + 风险评估 + 验证计划
  - **Superpowers/ECC 技能引用表**（从 meeting CLAUDE.md 第 5/6 节直接复用）
  - **WIP=1 规则**：一次只做一个功能
  - **完成门控**：验证通过 + 证据记录才能标记 passing
  - **会话结束清单**：更新 progress → 更新 feature_list → 记录风险 → 提交

### core/feature_list.json
- Python 项目占位符，包含示例功能条目
- 字段：id, priority, area, title, user_visible_behavior, status, verification[], evidence[], notes
- 状态值：not_started / in_progress / blocked / passing
- 规则：single_active_feature=true, passing_requires_evidence=true

### core/init.sh
- Python 专用：
  ```bash
  pip install -r requirements.txt  # 或 pip install -e ".[dev]"
  python -m pytest --tb=short -q   # 基线验证
  python -m mypy src/ --ignore-missing-imports  # 可选类型检查
  ```

### core/claude-progress.md
- 当前验证状态 + 会话日志模板

---

## 第二层：standard/（完整版 — core + 5 个扩展文件 + .claude/ 配置）

适用场景：中型项目、多会话开发、需要架构约束

```
standard/
├── CLAUDE.md                    # 增强版（含架构约束引用）
├── feature_list.json
├── init.sh
├── claude-progress.md
├── session-handoff.md           # 会话交接模板
├── clean-state-checklist.md     # 干净状态检查清单
├── docs/
│   └── ARCHITECTURE.md          # 架构文档模板
└── .claude/
    ├── settings.json            # 权限配置
    └── hooks.json               # 基础 hooks
```

### 新增文件说明

**session-handoff.md**
- 当前验证状态 / 本次变更 / 未完成项 / 下一步 / 关键命令

**clean-state-checklist.md**
- Python 专用检查项：
  - [ ] pytest 全部通过
  - [ ] mypy 无类型错误
  - [ ] ruff/flake8 无 lint 警告
  - [ ] 无 debug print/breakpoint 残留
  - [ ] 无未跟踪的敏感文件（.env, credentials）
  - [ ] claude-progress.md 已更新
  - [ ] feature_list.json 状态准确
  - [ ] 下一会话可直接 ./init.sh 继续

**docs/ARCHITECTURE.md**
- Python 项目架构模板：
  - 系统形状（产品描述、运行时表面）
  - 模块地图表格（模块 | 职责 | 入口 | 关联规格）
  - 层级模型（types → config → repo → service → api → cli/ui）
  - 硬依赖规则
  - 热点区域

**.claude/settings.json**
- 参考 meeting 项目的 settings.local.json，但通用化：
  - 允许 python/python3/pip/pytest/mypy/ruff 等常用命令
  - 允许 git 操作
  - 排除 venv/、.git/、__pycache__/ 读取
  - 不包含 macOS 特定路径（通用化）

**.claude/hooks.json**（基础 hooks）
- `PreCommit` hook：运行 pytest + ruff check
- `PostCommit` hook：提醒更新 claude-progress.md（如果未更新）

---

## 第三层：full/（全功能版 — standard + 高级文件 + scripts/ + 完整 .claude/ 生态）

适用场景：大型项目、团队协作、需要质量评估和自动化

```
full/
├── CLAUDE.md                    # 完整版（含所有引用）
├── feature_list.json
├── init.sh                      # 增强版（含架构检查）
├── claude-progress.md
├── session-handoff.md
├── clean-state-checklist.md     # 扩展版（含运行时验证）
├── quality-document.md          # 质量评分文档
├── evaluator-rubric.md          # 评估评分卡
├── docs/
│   └── ARCHITECTURE.md
├── scripts/
│   ├── check-architecture.sh    # 架构约束自动检查
│   └── session-cleanup.sh       # 会话结束自动清理
└── .claude/
    ├── settings.json
    ├── hooks.json               # 完整 hooks（含架构检查）
    ├── commands/
    │   ├── check.md             # /check — 运行完整验证
    │   ├── status.md            # /status — 查看项目状态
    │   └── handoff.md           # /handoff — 生成会话交接
    └── skills/
        └── project/
            └── SKILL.md         # 项目专属技能模板
```

### 新增文件说明

**quality-document.md**
- 按领域和架构层的质量评分（A/B/C/D）
- 表格格式：领域 | 等级 | 验证状态 | Agent 可读性 | 测试稳定性 | 关键差距

**evaluator-rubric.md**
- 6 维评估：正确性、验证、范围纪律、可靠性、可维护性、交接准备度
- 0-2 分制 + 判定（接受/修订/阻塞）

**scripts/check-architecture.sh**
- 自动检查 Python 项目架构约束：
  - src/ 中无相对 import 超出包边界
  - tests/ 中不直接 import 内部模块（应通过公开 API）
  - 无循环依赖
  - 敏感文件检查（.env 不在 git 中）

**scripts/session-cleanup.sh**
- 自动化会话结束：运行 pytest → ruff → mypy → 更新检查清单状态

**.claude/commands/**
- `/check`：运行 pytest + mypy + ruff，汇总结果
- `/status`：读取 feature_list.json + claude-progress.md，输出当前状态摘要
- `/handoff`：自动生成 session-handoff.md 内容

**.claude/skills/project/SKILL.md**
- 项目专属技能模板骨架（参考 meeting 项目的 SKILL.md 结构）
- 包含 metadata、工具列表、指导说明的占位符

**.claude/hooks.json**（完整版）
- `PreCommit`：pytest + ruff + check-architecture.sh
- `PostCommit`：更新 claude-progress.md 提醒
- `PreToolUse`（Edit）：提醒检查 TDD 是否先写了测试

---

## 所有模板的通用设计原则

1. **全中文内容**：所有说明、注释、模板文本用中文，代码标识符和命令保持英文
2. **占位符标记**：使用 `{{项目名称}}`、`{{项目描述}}` 等占位符，便于查找替换
3. **Python 专用**：init.sh 用 pip/pytest/mypy，验证命令用 pytest，lint 用 ruff
4. **融合两个来源**：
   - 课程：结构化工作流、WIP=1、feature list 三元组、三层验证
   - meeting 项目：TDD-strict、Human-in-the-Loop、Superpowers/ECC 引用、Python 标准

---

## 实施步骤

### Step 1：创建 core/ 目录（4 个文件）
- 生成 CLAUDE.md、feature_list.json、init.sh、claude-progress.md
- 关键参考文件：
  - `/root/projects/learn-harness-engineering/docs/en/resources/templates/CLAUDE.md`
  - `/root/projects/meeting/CLAUDE.md`

### Step 2：创建 standard/ 目录（core + 5 个扩展 + .claude/）
- 复制 core 内容并增强 CLAUDE.md（添加架构约束引用）
- 新增 session-handoff.md、clean-state-checklist.md、docs/ARCHITECTURE.md
- 新增 .claude/settings.json、.claude/hooks.json
- 关键参考文件：
  - `/root/projects/learn-harness-engineering/docs/en/resources/templates/session-handoff.md`
  - `/root/projects/learn-harness-engineering/docs/en/resources/templates/clean-state-checklist.md`
  - `/root/projects/meeting/.claude/settings.local.json`

### Step 3：创建 full/ 目录（standard + 高级文件 + 完整生态）
- 复制 standard 内容并增强
- 新增 quality-document.md、evaluator-rubric.md
- 新增 scripts/ 目录
- 新增 .claude/commands/ 和 .claude/skills/
- 关键参考文件：
  - `/root/projects/learn-harness-engineering/docs/en/resources/templates/quality-document.md`
  - `/root/projects/learn-harness-engineering/docs/en/resources/templates/evaluator-rubric.md`
  - `/root/projects/learn-harness-engineering/projects/project-05/starter/AGENTS.md`（最完整的实例）
  - `/root/projects/meeting/.claude/skills/meeting/SKILL.md`

### Step 4：创建 templates/README.md
- 三层级说明、使用方法、快速开始指南

---

## 验证

1. **结构验证**：`find templates/ -type f` 确认所有文件都在正确位置
2. **占位符检查**：`grep -r "{{" templates/` 确认所有占位符格式一致
3. **init.sh 可执行**：`chmod +x` 并确认 bash 语法正确 `bash -n templates/*/init.sh`
4. **JSON 有效性**：`python -m json.tool templates/*/feature_list.json`
5. **hooks/settings 格式**：确认 JSON 格式正确
6. **内容一致性**：full 包含 standard 的所有内容，standard 包含 core 的所有内容