Harness 工程实践

概述

Harness 工程是一种以 AI 辅助工具（如 Trae）为核心，结合多种技能（Skills）进行软件开发的工程模式。本规范旨在统一团队在使用 Harness 工程模式时的开发标准和最佳实践。

Harness 工程是什么

Harness 工程是一种新兴的软件开发方法论，它强调：

AI 辅助开发：利用 AI 工具（如 Trae）辅助完成编码、调试、审查等任务
技能组合：通过组合多种专业技能（Skills）解决复杂问题
自动化协作：通过自动化工具链提升开发效率和质量
持续集成：将 AI 辅助融入持续集成/持续部署（CI/CD）流程

依托的工具（Skills）

Harness 工程依托以下核心技能工具：

技能名称	功能描述	使用场景
`TRAE-code-review`	代码审查	审查合并请求、代码差异，提供代码质量反馈
`TRAE-debugger`	运行时调试	收集运行时证据，诊断复杂问题
`TRAE-security-review`	安全扫描	审查代码安全漏洞和风险
`brainstorming`	创意设计	探索用户意图、需求分析和设计规划
`test-driven-development`	测试驱动开发	实现功能或修复 bug 前编写测试
`systematic-debugging`	系统调试	遇到 bug、测试失败或意外行为时使用
`verification-before-completion`	完成前验证	完成任务前运行验证命令确认
`requesting-code-review`	请求代码审查	完成任务后请求审查验证工作

项目文档规范

文档目录结构

项目文档统一存放在 /docs 目录下，按功能模块进行组织：

docs/
├── standard/          # 开发规范文档
│   ├── index.md       # 规范概述
│   ├── frontend.md    # 前端规范
│   ├── backend.md     # 后端规范
│   └── harness.md     # Harness 工程规范
├── framework/         # 框架文档
├── auth/              # 权限模块文档
├── generator/         # 代码生成文档
├── micro/             # 微模块文档
└── mall/              # 商城业务文档

文档编写规范

使用 Markdown 格式：所有文档采用标准 Markdown 语法
文件命名：使用小写字母，单词之间用连字符 - 分隔
标题层级：使用 #、##、### 表示标题层级
代码引用：使用 [display_name](file:///absolute/path) 格式引用文件和代码元素
表格使用：使用表格展示结构化数据

忽略文件设置（Trae Ignore）

Trae Ignore 配置

项目应配置 .trae/.ignore 信息，告诉 Trae 忽略以下类型的文件：

文件类型	示例	说明
IDE 配置	`.idea/`, `.vscode/`	开发工具的配置目录
构建产物	`dist/`, `build/`, `node_modules/`	编译输出和依赖目录
日志文件	`*.log`, `logs/`	运行时日志文件
临时文件	`.tmp`, `.swp`	临时文件和备份文件
环境变量	`.env`, `.env.local`	包含敏感信息的配置文件
后端配置	`application-.yml`, `application-.properties`	包含敏感信息的配置文件
编辑器缓存	`.DS_Store`, `Thumbs.db`	操作系统生成的隐藏文件
依赖文件	`vendor/`, `target/`	第三方依赖和构建目标目录
测试覆盖率	`coverage/`, `htmlcov/`	测试覆盖率报告目录
版本控制	`.git/`, `.svn/`	版本控制系统目录

Trae Ignore 配置示例

markdown


## Ignore 配置
.idea/
.vscode/
node_modules/
dist/
build/
target/
vendor/
*.log
logs/
.env
.env.local
application-*.yml
application-*.properties
coverage/
htmlcov/

添加忽略文件的时机

项目初始化时：添加基础的忽略规则
引入新工具时：如 IDE、构建工具、测试框架等
发现敏感信息时：立即将相关文件加入忽略列表
团队协作时：统一忽略规则，避免不必要的干扰

项目文档体系

Harness 工程中的项目文档体系由 README、AGENTS.md 和 Story 三部分组成，形成完整的文档闭环。

README.md - 项目入口文档

README 是项目的入口文档，位于项目根目录，用于快速了解项目概况。

README 编写规范

项目简介：简要描述项目名称、功能定位和核心价值
快速开始：提供环境准备、安装步骤、运行命令
目录结构：展示项目的目录组织方式
功能特性：列举项目的主要功能模块
使用文档：提供详细的使用说明和示例
贡献指南：说明如何参与项目贡献
许可证说明：明确项目的开源许可证

README 示例结构

markdown

# 项目名称

## 项目简介
简要描述项目的功能、定位和目标用户。

## 快速开始
### 环境要求
列出运行项目所需的软硬件环境。

### 安装部署
提供详细的安装和部署步骤。

## 目录结构
说明项目各目录的功能和用途。

## 功能列表
- 功能点一
- 功能点二
- 功能点三

## 使用文档
提供详细的使用说明和示例代码。

## 贡献指南
说明代码规范、提交流程、审核标准。

## 许可证
MIT License

AGENTS.md - 任务记录文档

AGENTS.md 位于项目根目录，用于记录 AI 辅助开发过程中的任务执行情况和经验总结。

AGENTS.md 编写规范

Ignore 配置：定义 Trae 需要忽略的文件和目录
任务历史：按时间顺序记录完成的任务
规则沉淀：总结项目特定的开发规则
经验分享：记录开发过程中的技巧和注意事项

AGENTS.md 更新时机

任务完成时：每次完成任务后立即更新
规则变更时：项目规则调整时同步更新
经验积累时：总结出有价值的设计模式或最佳实践时添加
问题解决时：记录重大问题的解决方案

Story - 逻辑拆解文档

Story 是对复杂业务逻辑的详细拆解文档，通常位于功能模块目录下，用于记录设计思路和实现细节。

Story 编写规范

问题分析：描述要解决的问题或实现的需求
方案设计：详细说明技术方案和设计思路
实现步骤：分解为可执行的小步骤
代码示例：提供关键代码的实现示例
测试验证：说明如何验证功能的正确性
风险评估：识别潜在风险和应对措施

Story 命名规范

文件命名使用小写字母和连字符
格式：story-{功能名称}.md
示例：story-user-authentication.md、story-order-processing.md

Harness 工程实践 ​

概述 ​

Harness 工程是什么 ​

依托的工具（Skills） ​

项目文档规范 ​

文档目录结构 ​

文档编写规范 ​

忽略文件设置（Trae Ignore） ​

Trae Ignore 配置 ​

Trae Ignore 配置示例 ​

添加忽略文件的时机 ​

项目文档体系 ​

README.md - 项目入口文档 ​

README 编写规范 ​

README 示例结构 ​

AGENTS.md - 任务记录文档 ​

AGENTS.md 编写规范 ​

AGENTS.md 更新时机 ​

Story - 逻辑拆解文档 ​

Story 编写规范 ​

Story 命名规范 ​