HARNESS.md 方法论设计

学习目标

• 理解 HARNESS.md 的三重角色：设计手册、执行指南、质量门禁
• 掌握架构模式与陷阱的编码方式
• 了解可拆分的 guides/ 子文档系统
• 应用从 18+ 真实 Harness 中提炼的模式库

前置知识

本章涉及 Skill 渐进式知识管理，建议先阅读：

• Skill 渐进式知识管理

下文直接聚焦 HARNESS.md 的具体设计。

---

项目实践

HARNESS.md 的三重角色

HARNESS.md（~750 行）是整个项目的单一事实源，扮演三重角色：

角色	受众	内容
设计手册	人类开发者	架构模式、陷阱、最佳实践、后端映射表
执行指南	AI Agent	Phase 1-7 的 SOP，每个步骤的具体操作
质量门禁	Agent + CI	”不可协商”的原则与规则，测试标准

这种设计使得方法论本身成为可维护、可演进的项目资产——更新 HARNESS.md 就更新了所有生成 CLI 的行为标准。

结构解剖

HARNESS.md 的章节组织：

HARNESS.md
├── Purpose                    # 项目定位
├── General SOP                # Phase 1-7 标准流程
│   ├── Phase 1: Codebase Analysis
│   ├── Phase 2: CLI Architecture Design
│   ├── Phase 3: Implementation
│   ├── Phase 4: Test Planning
│   ├── Phase 5: Test Implementation
│   ├── Phase 6: Test Documentation
│   └── Phase 6.5: SKILL.md Generation
│       └── Phase 7: PyPI Publishing
├── Architecture Patterns & Pitfalls
│   ├── Use the Real Software
│   ├── The Rendering Gap
│   ├── MCP Backend Pattern
│   ├── Filter Translation Pitfalls
│   ├── Timecode Precision
│   ├── Output Verification Methodology
│   └── Testing Strategy
├── Principles & Rules
│   ├── Backend & Rendering
│   ├── CLI Design
│   ├── Testing
│   └── Documentation
├── Preview & Live Preview Norms
├── Directory Structure
└── Guides Reference

渐进式披露在 HARNESS.md 中的应用

2026-03-30 的 v0.2.0 更新（CHANGELOG 记录）对 HARNESS.md 进行了重新设计：

HARNESS.md progressive disclosure redesign. Detailed guides extracted into guides/ for on-demand loading. Phases 1–7 now contiguous.

关键变化：

• 详细内容（session-locking、filter-translation、mcp-backend 等）从 HARNESS.md 拆分为 guides/ 子文档
• Phase 1-7 变为连续可读的 SOP，不受细节打断
• Agent 需要细节时按需读取 guides/ 中的子文档

设计效果：HARNESS.md 保持精简可读，细节通过 guides/ 的引用表按需加载。

架构模式的编码方式

HARNESS.md 的 “Architecture Patterns & Pitfalls” 章节将工程经验编码为可执行指导：

### Use the Real Software — Don't Reimplement It

**This is the #1 rule.**

**The anti-pattern:** Building a Pillow-based image compositor to replace GIMP...

**The correct approach:**
1. Use the software's CLI/scripting interface as the backend
2. The software is a required dependency, not optional
3. Generate valid project/intermediate files then hand to real software

每个模式都包含：

• 问题描述：为什么这是个坑
• 反模式：错误的做法及其后果
• 正确方案：具体步骤
• 代码示例：可参考的伪代码

原则与规则的”不可协商”性

HARNESS.md 的 “Principles & Rules” 章节明确标注 “These are non-negotiable”：

Backend & Rendering：

• 真实软件是硬依赖，不允许优雅降级
• 每个滤镜必须有对应的渲染映射
• 操纵原生格式（MLT XML、ODF、SVG）

CLI Design：

• 失败时错误信息清晰
• 尽可能幂等
• 提供内省命令
• JSON 输出每个命令必须支持

Testing：

• E2E 必须调用真实软件
• 必须包含子进程测试
• 不信任退出码

Guides Reference 系统

guides/ 目录包含可拆分的专题文档：

文件	主题	引用时机
session-locking.md	会话文件锁	Phase 3 实现 session save 时
filter-translation.md	视频效果翻译	Phase 3 视频编辑 Harness
timecode-precision.md	非整数帧率处理	Phase 3/5 视频/音频 Harness
mcp-backend.md	MCP 服务器封装	Phase 3 无 CLI 软件
preview-methodology.md	Preview 设计规范	Phase 3/6.5 有 Preview 的 Harness
skill-generation.md	SKILL.md 生成	Phase 6.5
pypi-publishing.md	包发布	Phase 7

HARNESS.md 中的引用表让 Agent 自行判断需要读取哪些子文档。

后端映射表

HARNESS.md 末尾提供了一张覆盖 18+ 软件的后端映射表：

软件	后端 CLI	原生格式	系统包
LibreOffice	libreoffice --headless	.odt/.ods/.odp (ODF ZIP)	apt install libreoffice
Blender	blender --background --python	.blend-cli.json	apt install blender
GIMP	gimp -i -b '(script-fu ...)'	.xcf	apt install gimp
Inkscape	inkscape --actions="..."	.svg (XML)	apt install inkscape
Shotcut/Kdenlive	melt 或 ffmpeg	.mlt (XML)	apt install melt ffmpeg

这张表是 18+ 真实 Harness 实践的结晶，为新 Harness 开发提供快速参考。

---

问题与规避

问题	规避策略
HARNESS.md 过于冗长	v0.2.0 后拆分为 guides/ 子文档，渐进式加载
Agent 跳过关键规则	”non-negotiable” 明确标注，重复关键规则
新模式出现后文档过时	PR 到 HARNESS.md 是贡献流程的核心路径
不同软件的特殊情况	guides/ 按条件引用——视频读 filter-translation，MCP 读 mcp-backend

设计取舍

文档驱动 vs 代码驱动

选择：方法论写入 Markdown 文档，Agent 阅读执行。

原因：

• 文档对人类和 Agent 都友好
• 更新文档比改代码生成器成本低
• PR 到 HARNESS.md 是社区贡献的入口
• 文档是”模式库”而非”模板引擎”——Agent 理解后灵活应用

代价：依赖强模型。较弱的模型可能忽略关键规则。

为什么 “Principles & Rules” 独立于 SOP

选择：原则规则作为独立章节，而非内嵌在 SOP 中。

原因：

• SOP 按阶段组织，关注”做什么”
• 原则规则跨所有阶段，关注”不能做什么”
• 独立章节更容易被 Agent 作为全局约束加载
• 更新规则不需要改 SOP 内容

参考来源

• 源码验证：HARNESS.md 全文
• 源码验证：guides/ 目录全部 7 个子文档
• CHANGELOG 记录：v0.2.0 HARNESS.md progressive disclosure redesign