Skill: ai-acheng/harness-dev-standards (version 1.0.2)

--- name: harness-dev-standards description: Harness Engineering 开发规范体系 - 全流程质量门禁与自动治理标准。基于企业级全AI研发实践改进，提供完整的代码交付质量保障框架。Use when: (1) 启动新项目开发前, (2) 代码交付前做质量检查, (3) 需要标准化开发流程, (4) 执行架构评审、代码评审, (5) 排查依赖/环境问题 --- # 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](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 项目标准结构 ``` 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](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/standards.md) | 详细文件结构规范 + 命名规范 | | [references/checklist.md](references/checklist.md) | 完整交付检查清单模板 | | [references/remediation.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


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)