# harness-template **Repository Path**: SuHangWeb/harness-template ## Basic Information - **Project Name**: harness-template - **Description**: harness 模板 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-04 - **Last Updated**: 2026-06-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # .harness — 通用 AI 编辑器项目模板 > **一套定义，适配所有 AI 工具。团队协作不漂移，项目切换不重写。** --- ## 解决什么问题 AI 编辑器各自有一套"项目上下文"机制——Claude Code 读 `CLAUDE.md`，Cursor 读 `.cursorrules`，Copilot 读 `.github/copilot-instructions.md`。如果你的团队多人分别用不同工具，维护这些文件会让你陷入**配置漂移地狱**： ``` 你改了 CLAUDE.md ← 同事用的 Cursor 不知道 同事改了 .cursorrules ← 你用的 Claude Code 不知道 ↓ 同一个项目，AI 给的建议不一致 ``` 这套模板的方案：**把项目知识写成 Markdown 源文件，按需生成各工具的原生配置。** ``` .harness/knowledge/coding-standards.md (你编辑的源) │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ CLAUDE.md .cursorrules copilot-instructions.md (Claude Code) (Cursor) (Copilot) │ │ │ └───────────────┴───────────────┘ │ 一模一样的规范，不同工具原生消费 ``` --- ## 一句话核心原则 > **`.harness/` 是唯一编辑源。其他都是生成产物，不入 Git，随时重建。** --- ## 目录结构 ``` harness-template/ │ ├── README.md ← 本文件 ├── .gitignore ← 忽略 AI 生成产物 │ └── .harness/ ← ★ 通用层（拷贝到任何项目中） │ ├── harness.config.yaml ← 项目配置入口（技术栈、规范参数、生成规则） ├── generate-all.sh ← 一键生成所有 AI 工具适配 ├── README.md ← .harness 目录内部说明 ├── GETTING-STARTED.md ← 详细使用指南 │ ├── agents/ ← Agent 角色定义（工具无关） │ ├── architect.md ← 架构师：系统设计、技术选型 │ ├── coder.md ← 程序员：编码实现 │ ├── reviewer.md ← 审查员：Bug/安全/性能/可维护性 │ └── researcher.md ← 研究员：调研分析 │ ├── workflows/ ← 开发流程定义（工具无关） │ ├── feature-development.md ← 功能开发：设计→编码→审查 │ ├── bug-fix.md ← Bug修复：定位→复现测试→修复→回归 │ ├── code-review.md ← 代码审查：浏览→逐文件→整体评估 │ └── refactor.md ← 重构：评估→小步改→验证等价 │ ├── knowledge/ ← 项目知识（工具无关） │ ├── tech-stack.md ← 技术栈清单 │ ├── architecture.md ← 系统架构、模块划分 │ ├── coding-standards.md ← 编码规范 │ └── api-docs.md ← API 接口约定 │ ├── prompts/ ← Prompt 模板库 │ ├── system.md ← 系统级 Prompt（角色+行为准则） │ └── tasks.md ← 常见任务 Prompt 模板 │ ├── templates/ ← 项目模板 │ ├── pr.md ← PR 描述模板 │ ├── commit.md ← Commit 规范 │ └── task.md ← 任务拆分模板 │ ├── memory/ ← 项目记忆（跨工具共享） │ ├── decisions.md ← ADR 重要决策记录 │ ├── context.md ← 项目当前状态 │ └── learnings.md ← 经验教训 │ └── adapters/ ← ★ 适配层（每个 AI 工具一个子目录） ├── claude-code/generate.sh ← Claude Code 生成脚本 ├── cursor/generate.sh ← Cursor 生成脚本 ├── copilot/generate.sh ← GitHub Copilot 生成脚本 └── windsurf/generate.sh ← Windsurf 生成脚本 ``` --- ## 快速开始 ### 新项目 ```bash # 1. 拷贝模板 git clone git@github.com:your-org/harness-template.git /tmp/harness cp -r /tmp/harness/.harness ./my-new-project/ cp /tmp/harness/.gitignore ./my-new-project/ cd my-new-project # 2. 填写项目信息（三个必填项） vim .harness/harness.config.yaml # 技术栈、编码风格参数 vim .harness/knowledge/tech-stack.md # 具体技术选型和版本 vim .harness/knowledge/architecture.md # 系统架构 # 3. 根据情况可选编辑 # .harness/knowledge/coding-standards.md — 编码规范（模板已有通用版本） # .harness/knowledge/api-docs.md — API 约定 # .harness/memory/context.md — 当前项目阶段 # 4. 生成 AI 工具配置 bash .harness/adapters/claude-code/generate.sh # 如果你用 Claude Code bash .harness/adapters/cursor/generate.sh # 如果你用 Cursor # ... 或一键生成所有 bash .harness/generate-all.sh # 5. 开始用 AI 开发 claude # Claude Code 用户 # Cursor / Windsurf 用户：重启编辑器即可 ``` ### 接入现有项目 ```bash # 1. 把 .harness/ 放入项目根目录 cp -r /path/to/harness-template/.harness ./my-existing-project/ # 2. 把 .gitignore 的 AI 生成部分追加到你项目的 .gitignore # （见下方 "Git 管理" 一节） # 3. 如果有旧的 AI 配置文件，把内容迁移到 .harness/ # 旧 CLAUDE.md → knowledge/ + prompts/system.md # 旧 .cursorrules → knowledge/ # 迁移完成后删掉旧文件 # 4. 反向提炼当前项目的知识 # 看 package.json → knowledge/tech-stack.md # 看目录结构 → knowledge/architecture.md # 看 .eslintrc → knowledge/coding-standards.md # 5. 生成配置 bash .harness/generate-all.sh ``` --- ## 各 AI 工具使用方式 ### Claude Code ```bash bash .harness/adapters/claude-code/generate.sh ``` | 产物 | 作用 | |---|---| | `CLAUDE.md` | 每次会话自动注入系统提示词 | | `.claude/settings.json` | 权限控制、hooks、环境变量 | | `.claude/agents/` | Agent 角色（可在 Workflow 中通过 `agentType` 引用） | | `.claude/memory/` | 持久化记忆（跨会话保留） | | `.claude/workflows/` | 工作流 JS 骨架（可按需完善为可执行脚本） | **使用示例：** ``` # 在 Claude Code 会话中 "帮我按照 .harness/workflows/feature-development.md 流程开发用户注册功能" # 引用 Agent "用 reviewer Agent 审查 PR #42" # Workflow 中引用 Agent agent("审查", { agentType: "reviewer" }) ``` ### Cursor ```bash bash .harness/adapters/cursor/generate.sh ``` | 产物 | 作用 | |---|---| | `.cursorrules` | 项目主规则（自动加载） | | `.cursor/rules/coding-standards.mdc` | 编码规范（`alwaysApply: true`） | | `.cursor/rules/architecture.mdc` | 架构规则 | | `.cursor/rules/agent-*.mdc` | Agent 角色（手动 `@agent-architect` 引用） | **使用示例：** ``` # 在 Cursor Chat / Composer 中 @agent-architect 设计用户注册系统的模块划分 @agent-reviewer 审查当前文件的代码 @agent-coder 实现用户登录接口 ``` ### GitHub Copilot ```bash bash .harness/adapters/copilot/generate.sh ``` | 产物 | 作用 | |---|---| | `.github/copilot-instructions.md` | Copilot 项目指令（Chat + 代码补全） | 推送后在仓库 Settings → Copilot 中启用"使用项目指令"。 ### Windsurf ```bash bash .harness/adapters/windsurf/generate.sh ``` | 产物 | 作用 | |---|---| | `.windsurfrules` | Windsurf 项目规则（Chat + Cascade 模式） | --- ## Git 管理 ### 应该提交的 ``` .harness/agents/ ✅ Agent 角色定义 .harness/workflows/ ✅ 开发流程定义 .harness/knowledge/ ✅ 项目知识（核心资产） .harness/prompts/ ✅ Prompt 模板 .harness/templates/ ✅ PR/Commit/任务模板 .harness/memory/ ✅ 决策记录和经验（项目历史） .harness/harness.config.yaml ✅ 配置入口 .harness/generate-all.sh ✅ 生成脚本 .harness/adapters/ ✅ 适配器脚本 ``` ### 不应该提交的（生成产物） ```gitignore # === 以下由 .harness/adapters/ 生成，不入库 === .claude/ ❌ Claude Code 生成 CLAUDE.md ❌ Claude Code 生成 .cursor/ ❌ Cursor 生成 .cursorrules ❌ Cursor 生成 .github/copilot-instructions.md ❌ Copilot 生成 .windsurfrules ❌ Windsurf 生成 ``` ### 模板本身的 .gitignore 说明 模板仓库的 `.gitignore` 中，AI 生成产物行默认**注释掉了**（因为模板是空的，没有这些文件）。拷贝到实际项目后，**取消注释**即可生效。或者 `generate.sh` 运行时会自动追加。 --- ## 扩展指南 ### 场景 1：添加新的 AI 工具 比如出现了一个叫 `SuperAI` 的新编辑器。只需两步： **Step 1: 创建 adapter 目录** ```bash mkdir -p .harness/adapters/super-ai ``` **Step 2: 写 `generate.sh`** ```bash #!/usr/bin/env bash # .harness/adapters/super-ai/generate.sh set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" HARNESS_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" PROJECT_ROOT="$(cd "$HARNESS_DIR/.." && pwd)" OUTPUT="$PROJECT_ROOT/.superairules" # 合并 knowledge/ 和 prompts/ 生成 SuperAI 的规则文件 cat "$HARNESS_DIR/prompts/system.md" > "$OUTPUT" echo "" >> "$OUTPUT" cat "$HARNESS_DIR/knowledge/tech-stack.md" >> "$OUTPUT" echo "" >> "$OUTPUT" cat "$HARNESS_DIR/knowledge/coding-standards.md" >> "$OUTPUT" echo "" >> "$OUTPUT" cat "$HARNESS_DIR/knowledge/architecture.md" >> "$OUTPUT" echo "✓ .superairules 已生成" ``` **Step 3: 在 `generate-all.sh` 中添加** ```bash # 在 generate-all.sh 的末尾前加入 echo "▶ SuperAI" bash "$ADAPTERS_DIR/super-ai/generate.sh" echo "" ``` **不用改通用层的任何一个 `.md` 文件。** --- ### 场景 2：添加新的 Agent 角色 比如加一个 `devops.md`。 **Step 1: 创建角色定义** ```bash vim .harness/agents/devops.md ``` ```markdown # DevOps — 运维工程师 Agent ## 角色定位 你是 DevOps 工程师。专注于 CI/CD、基础设施即代码、部署和监控。 ## 核心职责 1. CI/CD 流水线设计与维护 2. Docker/K8s 配置 3. 监控和告警配置 ... ## 输出格式 ... ``` **Step 2: 各 adapter 会自动发现** 因为 `generate.sh` 遍历 `agents/*.md`，新文件会被自动包含。Claude Code 生成 `.claude/agents/devops.md`，Cursor 生成 `.cursor/rules/agent-devops.mdc`。 --- ### 场景 3：添加新的工作流 ```bash vim .harness/workflows/deploy.md ``` ```markdown # 部署工作流 ## 触发条件 - 合并到 main 分支后 ## 执行步骤 ### Step 1: 构建检查 ... ### Step 2: 部署到 Staging ... ### Step 3: 冒烟测试 ... ### Step 4: 部署到生产 ... ``` adapter 会自动为它生成对应工具的格式。 --- ### 场景 4：自定义 adapter 生成内容 每个 `generate.sh` 都是独立的 Shell 脚本，可以自由修改。常见定制： **调整生成哪些文件：** ```bash # 在 generate.sh 中修改 knowledge_files 数组 local knowledge_files=( "knowledge/tech-stack.md" "knowledge/architecture.md" "knowledge/coding-standards.md" # "knowledge/api-docs.md" ← 不想让 Copilot 看到 API 文档，注释掉 ) ``` **自定义 permission 白名单（Claude Code）：** ```bash # 在 generate_settings() 中添加你自己的命令 "Bash(docker compose *)", "Bash(kubectl get *)", "Bash(terraform plan)", ``` **自定义生成模板的格式：** adapter 本质是"读取 Markdown → 拼装成目标格式"。如果你对某个工具的生成格式有特殊要求，改 `generate.sh` 里的 `cat >` 模板即可。 --- ### 场景 5：在公司级共享公共部分 如果你有 20 个微服务仓库，想把**公司级编码规范**共享，**每个服务自己的架构**各自维护： ```bash # 方案 A：Git Submodule git submodule add git@github.com:company/harness-common.git .harness/common # 在 adapter 中配置 knowledge 路径指向 submodule # 方案 B：脚本拉取 # 在 generate.sh 开头加入 curl -s https://company-internal/standards/coding-standards.md \ > "$HARNESS_DIR/knowledge/coding-standards.md" ``` --- ### 场景 6：把 `.harness/` 做成团队脚手架 把本仓库 fork 一份，填上公司通用的编码规范和技术栈偏好，放内部 GitLab。新项目启动时： ```bash # 一行命令搞定 npx degit company/harness-template/.harness ./my-project/.harness # 或 git clone --depth 1 git@gitlab.com:company/harness-template.git /tmp/h cp -r /tmp/h/.harness ./ rm -rf /tmp/h ``` --- ## 工作流关系图 每个工作流文档中定义的 Agent 参与关系： ``` feature-development 工作流 ┌──────────────────────────┐ │ │ 需求 ──→ architect ──→ coder ──→ reviewer ──→ PR (设计) (实现) (审查) │ │ └──── 发现问题 ────────────┘ (回到设计) bug-fix 工作流 ┌─────────────────────────────────┐ │ │ Bug ──→ researcher ──→ coder ──→ coder ──→ reviewer ──→ Merge (定位根因) (写复现测试) (修复) (回归检查) ``` --- ## 文件职责速查 | 我要做什么 | 编辑哪个文件 | |---|---| | 告诉 AI 用什么语言/框架/库 | `harness.config.yaml` + `knowledge/tech-stack.md` | | 告诉 AI 代码怎么命名、怎么格式化 | `knowledge/coding-standards.md` | | 告诉 AI 系统怎么分层、模块怎么划分 | `knowledge/architecture.md` | | 告诉 AI API 地址和格式约定 | `knowledge/api-docs.md` | | 定义 AI 的角色行为准则 | `prompts/system.md` | | 定义"审查代码时要检查什么" | `agents/reviewer.md` | | 定义"修 Bug 的步骤" | `workflows/bug-fix.md` | | 记录"上次为什么选了 Redis 而不是 Memcached" | `memory/decisions.md` | | 记录"当前 Sprint 做什么" | `memory/context.md` | | 生成 PR 描述 | 用 `templates/pr.md` | | 支持一个新的 AI 编辑器 | 加 `adapters//generate.sh` | | 加一个新的开发流程 | 加 `workflows/.md` | | 加一个新的 Agent 角色 | 加 `agents/.md` | --- ## 常见问题
Q: 和直接把规则写进 .cursorrules 有什么区别？ 直接写 = 绑定了一个工具。换 Cursor → Windsurf 要重写。团队里有人用 Claude Code = 再维护一份 `CLAUDE.md`。这套模板让你写一次，四处生成。
Q: 生成产物要提交到 Git 吗？ 不要。它们由 `.gitignore` 忽略。队友各自本地运行 `generate.sh`。如果嫌麻烦，加到 `make setup` 或 CI 里即可。
Q: 我有多个项目，每个都要拷一份 .harness 吗？ 是的，每个项目拷一份。结构一样，但 `knowledge/` 和 `memory/` 的内容不同——每个项目有自己的技术栈和架构。公共部分（公司编码规范）可以提取到独立仓库用 submodule 引用。
Q: 如果我做了不该做的改动，怎么恢复？ 改 `.harness/` 里的源文件 = 改了真实数据（有 Git 历史保护）。改生成产物 = 无所谓，删掉重新 `generate.sh` 就行。
Q: 模板用什么写的，依赖什么？ 零依赖。源文件全是 Markdown，adapter 脚本是 Bash（Windows 用 Git Bash 或 WSL）。不需要安装任何东西。