Harness Engineering 开发规范体系
核心哲学 "质量不是检查出来的，是构建出来的"
基于 Harness Engineering 理念 + 腾讯全 AI 研发实践，构建从需求到交付的全链路质量保障体系。
🚀 快速启动
新项目初始化检查清单
每次启动新项目必须执行：
# 1. 检查目录结构是否符合标准
# 2. 检查 package.json 依赖完整性
# 3. 检查 .env.example 配置完整性
# 4. 检查 README 文档完整性
🔐 质量门禁 (Quality Gates)
每次交付必须通过以下 6 道门禁：
✅ 需求完整清晰，无模糊点
✅ 所有需求点已记录到任务追踪
✅ 技术可行性已验证
✅ 依赖边界已明确
✅ 技术选型适合单人开发
✅ 文件结构清晰，符合标准化规范
✅ 依赖最小化，无冗余包
✅ 扩展性设计合理
参考：查看 references/standards.md 标准化文件结构
✅ 语法正确，无 TypeScript/JavaScript 错误
✅ import 路径全部正确
✅ 命名规范清晰（camelCase 变量、PascalCase 组件）
✅ 不遗漏任何功能点
✅ 类型定义完整，无 any 滥用
✅ package.json 包含所有需要的依赖
✅ 无多余依赖（depcheck 验证）
✅ 依赖版本稳定（非 alpha/beta）
✅ lockfile 已提交（pnpm-lock.yaml / package-lock.json）
工具：运行 scripts/depcheck.sh 自动检查
✅ .env.example 包含所有需要的配置
✅ 每个配置项有说明注释
✅ 敏感信息不提交到 git
✅ .gitignore 配置正确
✅ 所有需求点都已实现
✅ 项目能正常启动
✅ README 写清楚使用方法
✅ 构建无错误（npm run build 验证）
🤖 自动治理 (Auto Remediation)
出现以下问题时，自动修复，无需人工干预：
问题类型 自动修复策略
依赖安装报错 分析错误 → 修改版本号或移除多余依赖
import 路径错误 自动查找正确路径修复
语法错误 自动修正 TypeScript/JavaScript 语法
启动失败 读取错误日志 → 修复后重新检查
类型错误 补全类型定义或修正类型不匹配
修复流程：
识别错误信息
定位问题代码位置
应用修复策略
验证修复结果
重复直到问题解决
📁 标准化文件结构
Next.js 项目标准结构
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 正确，不提交敏感文件
🛠️ 内置工具脚本
依赖检查脚本 # 运行依赖检查 ./scripts/depcheck.sh
功能：
检测未使用的依赖
检测缺失的依赖
检测版本冲突
生成修复建议
代码质量扫描脚本 # 运行代码质量扫描 ./scripts/quality-scan.sh
功能：
TypeScript 类型检查
ESLint 规则检查
命名规范检查
import 路径验证
📋 交付前检查清单
交付前逐项确认：
需求门禁：所有需求点实现完毕
架构门禁：文件结构符合标准
编码门禁：无语法/类型错误
依赖门禁：依赖干净无冗余
环境门禁：.env.example 完整
交付门禁：项目能正常启动构建
README：包含完整使用说明
📚 参考文档
文档 内容
references/standards.md 详细文件结构规范 + 命名规范
references/checklist.md 完整交付检查清单模板
references/remediation.md 常见问题自动修复策略库
💡 设计理念
为什么这样设计？
前置质量 - 把质量检查左移到开发过程每个环节，不是最后才检查
自动修复 - 能自动修的绝不麻烦人，解放生产力
标准化 - 降低认知负担，所有项目看起来都一样
渐进式 - 不追求完美，每次交付比上一次更好
和传统开发流程的区别
传统流程 Harness Engineering
最后统一测试 每一步都有质量门禁
人找问题 问题自动暴露并修复
每个项目结构都不一样 标准化结构，上手成本为 0
依赖问题靠经验解决 自动检测并给出修复方案
"The best code is the code you don't have to think about." - Harness Engineering Philosophy
by