Harness Engineering 开发规范体系#

核心哲学#

"质量不是检查出来的，是构建出来的"

基于 Harness Engineering 理念 + 企业级全AI研发实践，构建从需求到交付的全链路质量保障体系。

---

🚀 快速启动#

新项目初始化检查清单#

每次启动新项目必须执行：

bash

# 1. 检查目录结构是否符合标准
# 2. 检查 package.json 依赖完整性
# 3. 检查 .env.example 配置完整性
# 4. 检查 README 文档完整性

---

🔐 质量门禁 (Quality Gates)#

每次交付必须通过以下 6 道门禁：

1. 需求门禁 (Requirement Gate)#

• ✅ 需求完整清晰，无模糊点
• ✅ 所有需求点已记录到任务追踪
• ✅ 技术可行性已验证
• ✅ 依赖边界已明确

2. 架构门禁 (Architecture Gate)#

• ✅ 技术选型适合单人开发
• ✅ 文件结构清晰，符合标准化规范
• ✅ 依赖最小化，无冗余包
• ✅ 扩展性设计合理

参考： 查看 references/standards.md 标准化文件结构

3. 编码门禁 (Coding Gate)#

• ✅ 语法正确，无 TypeScript/JavaScript 错误
• ✅ import 路径全部正确
• ✅ 命名规范清晰（camelCase 变量、PascalCase 组件）
• ✅ 不遗漏任何功能点
• ✅ 类型定义完整，无 any 滥用

4. 依赖门禁 (Dependency Gate)#

• ✅ package.json 包含所有需要的依赖
• ✅ 无多余依赖（ depcheck 验证）
• ✅ 依赖版本稳定（非 alpha/beta）
• ✅ lockfile 已提交（pnpm-lock.yaml / package-lock.json）

工具： 运行 scripts/depcheck.sh 自动检查

5. 环境门禁 (Environment Gate)#

• ✅ .env.example 包含所有需要的配置
• ✅ 每个配置项有说明注释
• ✅ 敏感信息不提交到 git
• ✅ .gitignore 配置正确

6. 交付门禁 (Delivery Gate)#

• ✅ 所有需求点都已实现
• ✅ 项目能正常启动
• ✅ README 写清楚使用方法
• ✅ 构建无错误（ npm run build 验证）

---

🤖 自动治理 (Auto Remediation)#

出现以下问题时， 自动修复，无需人工干预：

问题类型自动修复策略依赖安装报错分析错误 → 修改版本号或移除多余依赖import 路径错误自动查找正确路径修复语法错误自动修正 TypeScript/JavaScript 语法启动失败读取错误日志 → 修复后重新检查类型错误补全类型定义或修正类型不匹配

修复流程：

1. 识别错误信息
2. 定位问题代码位置
3. 应用修复策略
4. 验证修复结果
5. 重复直到问题解决

---

📁 标准化文件结构#

Next.js 项目标准结构#

text

project-name/
├── app/                    # Next.js App Router
│   ├── page.tsx            # 首页
│   ├── layout.tsx          # 全局布局
│   └── globals.css         # 全局样式
├── lib/                   # 工具库、第三方客户端
├── public/                 # 静态资源
├── .env.example            # 环境变量示例
├── .gitignore              # git忽略规则
├── package.json
├── tsconfig.json
├── README.md               # 必须写清楚
└── *-init.sql              # 数据库初始化SQL

README 必须包含：

• 项目介绍
• 配置步骤
• 启动命令
• 环境变量说明

详细规范： 查看 references/standards.md

---

✅ 代码质量标准#

TypeScript 规范#

• ✅ 类型正确，无隐式 any
• ✅ 命名清晰，变量名表达用途
• ✅ 注释够用，不冗余
• ✅ 函数单一职责
• ✅ 避免深层嵌套（超过 3 层考虑重构）

项目规范#

• ✅ README 完整，新人能按文档启动
• ✅ 环境配置说明清晰
• ✅ 依赖干净，无未使用包
• ✅ gitignore 正确，不提交敏感文件

---

🛠️ 内置工具脚本#

依赖检查脚本#

bash

# 运行依赖检查
./scripts/depcheck.sh

功能：

• 检测未使用的依赖
• 检测缺失的依赖
• 检测版本冲突
• 生成修复建议

代码质量扫描脚本#

bash

# 运行代码质量扫描
./scripts/quality-scan.sh

功能：

• TypeScript 类型检查
• ESLint 规则检查
• 命名规范检查
• import 路径验证

---

📋 交付前检查清单#

交付前逐项确认：

• 需求门禁：所有需求点实现完毕
• 架构门禁：文件结构符合标准
• 编码门禁：无语法/类型错误
• 依赖门禁：依赖干净无冗余
• 环境门禁：.env.example 完整
• 交付门禁：项目能正常启动构建
• README：包含完整使用说明

---

📚 参考文档#

文档内容references/standards.md详细文件结构规范 + 命名规范references/checklist.md完整交付检查清单模板references/remediation.md常见问题自动修复策略库

---

💡 设计理念#

为什么这样设计？#

1. 前置质量 - 把质量检查左移到开发过程每个环节，不是最后才检查
2. 自动修复 - 能自动修的绝不麻烦人，解放生产力
3. 标准化 - 降低认知负担，所有项目看起来都一样
4. 渐进式 - 不追求完美，每次交付比上一次更好

和传统开发流程的区别#

传统流程Harness Engineering最后统一测试每一步都有质量门禁人找问题问题自动暴露并修复每个项目结构都不一样标准化结构，上手成本为0依赖问题靠经验解决自动检测并给出修复方案

---

"The best code is the code you don't have to think about." - Harness Engineering Philosophy