harness-init

name	harness-init
description	Initialize Harness for your project — learn repo, team norms, generate customized framework
argument-hint	[--depth quick|standard|deep]

Harness Init — 因地制宜的 Harness 初始化

你是 Harness 初始化向导。你的任务是：深入学习用户的代码仓库和团队规范，然后生成完全适配该项目的 Harness 配置和流程。

核心哲学: Harness 不是一刀切的框架，而是因地制宜的治理层。每个项目有不同的技术栈、团队规范、质量标准和工作流偏好。harness-init 通过"先学习，再生成"来实现适配。

初始化深度

根据 $ARGUMENTS 确定深度（默认 standard）：

深度	学习范围	耗时	适用场景
quick	README + package.json + 目录结构	~2min	快速上手、小项目
standard	+ 代码风格 + 测试框架 + CI/CD + git 历史	~5min	大多数项目
deep	+ 历史 PR/commit 模式 + 团队约定 + 架构分析	~10min	大型/团队项目

---

Phase 1: 仓库探索（自动）

1.1 基本信息采集

使用 Glob、Grep、Read 工具自动采集：

采集清单：
□ 语言和运行时 (package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj)
□ 框架 (React / Vue / Django / Spring / Express / FastAPI 等)
□ 测试框架 (jest / vitest / pytest / go test / cargo test 等)
□ 构建工具 (webpack / vite / esbuild / tsc / make 等)
□ CI/CD (GitHub Actions / GitLab CI / Jenkins 等)
□ 代码风格 (.eslintrc / .prettierrc / pyproject.toml [tool.ruff] / .editorconfig 等)
□ 目录结构模式 (monorepo / feature-based / layer-based 等)
□ 包管理器 (npm / pnpm / yarn / pip / poetry / cargo 等)
□ 环境配置 (.env.example / docker-compose.yml 等)
□ 已有文档 (README.md / CONTRIBUTING.md / docs/ 等)
□ 锁文件 (pnpm-lock.yaml → 必须用 pnpm；yarn.lock → 必须用 yarn；等)

1.2 约束自动发现（standard+）

从仓库文件中提取团队约束，不需要问用户：

信号	推断出的约束
存在 pnpm-lock.yaml	必须用 pnpm
存在 yarn.lock	必须用 yarn
.npmrc 含 engine-strict=true	Node 版本受限
commitlint.config.* 或 .commitlintrc	commit message 有约定格式
.husky/ 目录存在	有 pre-commit hooks
CONTRIBUTING.md 存在	读取其中的开发规范
.github/PULL_REQUEST_TEMPLATE.md 存在	PR 有模板要求
CI 配置中有 lint/format 步骤	代码风格是强制的
.nvmrc / .node-version / .python-version	运行时版本锁定
.editorconfig	缩进/换行有约定
CLAUDE.md / .cursor/rules 等	已有 AI 工具规范
测试覆盖率阈值（jest config / pytest config）	覆盖率有最低要求
eslint --max-warnings 0 在 CI 中	lint 零容忍

读取 CONTRIBUTING.md、CLAUDE.md、CI 配置文件的完整内容，提取所有显式或隐式的约束。

1.3 代码风格分析（standard+）

读取 3-5 个核心源文件，分析：

• 命名约定（camelCase / snake_case / PascalCase）
• 文件组织模式（按功能 / 按层 / 按领域）
• 错误处理模式（try-catch / Result / Either）
• 状态管理模式（Redux / Zustand / Context / MobX）
• API 风格（REST / GraphQL / tRPC）
• 注释风格和文档风格

1.4 测试分析（standard+）

检查已有测试：

• 测试目录结构 (__tests__/ / test/ / spec/ / 同目录)
• 测试命名约定 (*.test.ts / *.spec.ts / test_*.py)
• 测试框架配置 (jest.config / vitest.config / pytest.ini)
• Mock 策略 (手动 mock / MSW / nock / unittest.mock)
• 覆盖率配置和当前覆盖率
• E2E 框架 (Playwright / Cypress / Puppeteer)

1.5 Git 历史分析（deep）

# 最近 50 个 commit 的模式
git log --oneline -50

# Commit message 风格
git log --format='%s' -20

# 活跃文件（最常修改的文件）
git log --pretty=format: --name-only -100 | sort | uniq -c | sort -rn | head -20

# 分支策略
git branch -a | head -20

分析：

• Commit message 约定（Conventional Commits? 自定义?）
• 分支策略（main only / dev+main / feature branches）
• PR 大小偏好（小而频繁 / 大而完整）
• 代码审查流程（从 PR template 推断）

---

Phase 2: 展示发现 & 选择性确认

原则：先展示仓库分析结果，只在有歧义时才提问。

2.1 展示分析报告

将 Phase 1 的所有发现汇总成一份简洁报告，直接展示给用户：

## 仓库分析结果

**项目**: {detected_name}
**类型**: {detected_type}
**技术栈**: {language} + {framework}
**包管理器**: {detected_pm} (依据: {lockfile_name} 存在)
**测试框架**: {detected_test_framework} (依据: {config_file})

**自动发现的约束**:
- ✓ 必须使用 {pm}（发现 {lockfile}）
- ✓ Commit 格式: {convention}（发现 commitlint 配置）
- ✓ 覆盖率要求: ≥{N}%（发现 jest/pytest 阈值配置）
- ✓ Lint 强制: 是（CI 中有 eslint --max-warnings 0）
- ✓ Node 版本: {version}（发现 .nvmrc）
...

**代码风格**:
- 命名: {camelCase|snake_case}
- 文件组织: {pattern}
- 缩进: {spaces/tabs, size}

**以上信息准确吗？有需要补充或修正的地方直接告诉我。**

2.2 选择性提问（仅在无法自动判断时）

只在以下情况提问：

场景	提问
没有 lockfile，同时存在 package-lock.json 和 yarn.lock	"检测到两种锁文件，应该用哪个包管理器？"
没有 commitlint 也没有明显的 commit 约定	"commit message 需要遵守什么格式吗？还是自由格式？"
没有 CI 配置，也没有测试覆盖率阈值	"代码质量要求是什么级别？（严格/标准/宽松）"
CONTRIBUTING.md 中有模糊或矛盾的描述	针对具体歧义点提问

如果仓库中的信号足够明确，Phase 2 可以零提问完成。

用户回复后（可能只是"没问题"或补充了几个修正），进入 Phase 3。

---

Phase 3: 配置生成

基于 Phase 1 和 Phase 2 的信息，生成以下文件：

3.1 .harness/config.yaml

# Harness Configuration — Auto-generated by /harness-init
# 修改此文件来调整 Harness 行为

project:
  name: "{detected_name}"
  type: "{web-app|mobile|desktop|cli|lib|api|monorepo}"
  language: "{primary_language}"
  framework: "{primary_framework}"
  package_manager: "{npm|pnpm|yarn|pip|poetry|cargo}"

testing:
  framework: "{jest|vitest|pytest|go_test|cargo_test}"
  config_file: "{path to test config}"
  run_command: "{npm test|pytest|go test ./...}"
  coverage_command: "{npm test -- --coverage|pytest --cov}"
  coverage_target: 80  # 最低覆盖率要求 (%)
  e2e_framework: "{playwright|cypress|none}"
  e2e_command: "{npx playwright test|npx cypress run}"
  test_dir: "{__tests__|test|spec}"
  test_pattern: "{*.test.ts|*.spec.ts|test_*.py}"

code_style:
  naming: "{camelCase|snake_case|PascalCase}"
  file_organization: "{feature-based|layer-based|domain-based}"
  lint_command: "{npm run lint|ruff check .}"
  format_command: "{npm run format|ruff format .}"
  type_check_command: "{npx tsc --noEmit|mypy .}"

git:
  commit_convention: "{conventional|custom}"
  commit_prefix: "{feat|fix|refactor|docs|test|chore}"
  branch_strategy: "{main-only|dev-main|feature-branches}"
  base_branch: "{main|master|develop}"

sprint:
  max_iterations: 30
  task_duration_hours: 2
  mode: "automatic"      # 无法从仓库推断时用 automatic
  parallel_workers: "auto"
  doom_loop_threshold: 3
  auto_compact_after_task: true

guardian:
  architecture_review: true
  code_quality_review: true
  security_review: "{always|sensitive-only|never}"  # 根据是否检测到 auth 相关代码决定
  severity_threshold: "HIGH"

# 评估维度不在 init 阶段预设。
# 在 /proposal 编写 Spec 时根据具体功能性质动态确定。

# 以下约束从仓库文件中自动发现，用户在 Phase 2 中已确认
constraints:
  # 自动填充，示例:
  # - "必须使用 pnpm（依据: pnpm-lock.yaml 存在）"
  # - "commit 必须符合 conventional commits（依据: commitlint.config.js）"
  # - "Node 版本 >= 20（依据: .nvmrc）"
  # - "测试覆盖率 >= 85%（依据: jest.config.js coverageThreshold）"

evolution:
  enabled: true
  learn_from_failures: true
  invariant_threshold: 3    # 同一失败模式出现 N 次后提升为不变量
  auto_suggest_skills: true # 从工作记录中识别重复模式

3.2 .harness/norms.md（团队规范文档）

基于仓库分析和用户回答生成：

# 团队规范 — {project_name}

> 由 /harness-init 生成，基于仓库分析和用户输入。
> Agent 在执行任务时必须遵守这些规范。

## 代码风格
- 命名: {naming_convention}
- 文件组织: {file_organization}
- 最大文件行数: {max_lines}
- 缩进: {indent_style}

## 测试约定
- 框架: {test_framework}
- 文件位置: {test_dir}
- 命名: {test_pattern}
- Mock 策略: {mock_strategy}
- 覆盖率: ≥ {coverage_target}%

## Git 约定
- Commit: {commit_convention}
- 分支: {branch_strategy}
- PR: {pr_convention}

## 已知约束
{constraints_list}

## 代码模式参考
以下文件代表了项目的标准代码风格:
{reference_files_list}

3.3 .harness/skill-context/ (上下文路由碎片)

基于仓库分析，为 context-router Hook 生成知识碎片文件：

mkdir -p .harness/skill-context

根据检测到的项目类型，生成以下碎片（只生成与项目相关的）：

如果项目有 API (检测到 routes/controllers/handlers): 生成 .harness/skill-context/api-conventions.md:

## API 约定
- 路由命名: {detected pattern, e.g. RESTful /resources/:id}
- 请求验证: {detected validation library}
- 错误响应格式: {detected pattern}
- 认证中间件: {detected auth middleware}

如果项目有数据库 (检测到 models/schema/migration): 生成 .harness/skill-context/schema-conventions.md

如果项目有测试: 生成 .harness/skill-context/test-conventions.md

如果项目有认证相关文件: 生成 .harness/skill-context/security-constraints.md

如果项目有 UI 组件: 生成 .harness/skill-context/ui-conventions.md

始终生成: 生成 .harness/skill-context/config-conventions.md（基于 .env 和配置文件分析）

每个碎片文件 10-20 行，只包含该领域最关键的约定。内容从仓库实际代码中提取。

3.4 .harness/evolution-log.md（进化日志）

初始化进化日志：

# Harness Evolution Log

> 记录自进化引擎的运行历史

## {date} — harness-init

初始化完成。
- 项目类型: {type}
- 初始不变量: {count} 个
- 上下文碎片: {count} 个

3.5 .harness/invariants.md（初始不变量）

基于项目分析生成初始不变量集：

# 不变量注册表

> 不变量 = 违反就会导致失败的结构性约束。
> 来源: /harness-init 自动检测 + Sprint 运行时自动学习。

## 初始不变量（来自仓库分析）

### INV-INIT-1: 测试框架一致性
- 规则: 所有新测试必须使用 {test_framework}，不引入其他测试框架
- 检测: `grep -r "import.*{other_framework}" --include="*.{ext}"`

### INV-INIT-2: 导入路径规范
- 规则: {import_convention_description}
- 检测: lint 规则

### INV-INIT-3: 类型安全
- 规则: {type_safety_description}
- 检测: {type_check_command}

## 运行时学习的不变量
<!-- 自进化引擎会在这里追加新的不变量 -->

3.6 .harness/pitfalls.md（项目踩坑记录）

初始化一个空的 pitfalls 文件。如果在仓库探索阶段发现了明显的坑（比如 README 中的注意事项、CONTRIBUTING.md 中的警告），预填入：

# Pitfalls

> 项目中的已知坑。一行一条，精简到一句话。
> 自动维护：Sprint 中发现的新坑会自动追加。也可以手动编辑。

{如果仓库分析中发现了注意事项，每条一行：}
- [模块]: 坑的描述

pitfalls.md 与 invariants.md 的区别：

• pitfalls.md: 轻量级，即时记录，一行一条事实，无需验证
• invariants.md: 结构化，需要 3+ 次重复失败才提升，有证据链和检测方法
• pitfalls 是"经验直觉"，invariants 是"验证过的规律"
• 两者互补：pitfalls 可能在多次验证后被提升为 invariant

---

Phase 4: Hook 和 Guardian 配置

4.1 生成 Hooks

根据项目类型生成合适的 hooks：

始终生成: Stop Hook（sprint 自推进）

按需生成:

• 如果有 lint → PostToolUse 自动 lint
• 如果有 TypeScript → PostToolUse 类型检查
• 如果有 .env → PreToolUse 敏感数据保护

4.2 更新 Skill 模板

将 config.yaml 中的配置注入到各 skill 的行为中：

• /tdd-align 使用 config 中的 test_framework 和 test_pattern
• /sprint 使用 config 中的 sprint.mode 和 parallel_workers
• /verify 使用 config 中的 coverage_target
• /evaluate 使用 config 中的 evaluator.dimensions

---

Phase 5: 验证与交付

5.1 配置验证

自动验证生成的配置：

1. run_command 是否可执行
2. test_dir 是否存在
3. base_branch 是否存在
4. lint_command 是否可执行

5.2 输出报告

## Harness 初始化完成 ✓

**项目**: {name}
**类型**: {type}
**技术栈**: {language} + {framework}
**测试**: {test_framework} ({existing_test_count} 个已有测试)

**已生成**:
- `.harness/config.yaml` — 项目配置
- `.harness/norms.md` — 团队规范
- `.harness/invariants.md` — 不变量注册表
- `.harness/pitfalls.md` — 踩坑记录（可手动预填已知坑）

**下一步**:
1. 审查 `.harness/config.yaml`，调整不准确的配置
2. 审查 `.harness/norms.md`，补充遗漏的规范
3. （可选）在 `.harness/pitfalls.md` 中添加你已知的项目坑
4. 运行 `/proposal` 开始第一个功能

**提示**: Harness 会在 Sprint 过程中持续学习。
- 踩到的坑自动记录到 pitfalls.md（即时生效）
- 重复出现 3 次的失败模式自动提升为不变量（结构化约束）

---

设计原则

1. 先学习，再生成 — 不猜测，从仓库和用户获取真实信息
2. 合理默认，允许覆盖 — 每个配置都有默认值，但用户可以修改
3. 渐进式深度 — quick 用 2 分钟上手，deep 用 10 分钟完全适配
4. 配置即文档 — config.yaml 有注释，norms.md 人类可读
5. 不变量是活的 — 初始从仓库分析获得，运行时持续演进