setup-harness

Setup Harness

为任意代码仓库构建知识层脚手架。扫描、推断、填充。

通过 npx 安装：

npx skills add fellowship-dev/dogfooded-skills/ops/setup-harness

适用场景

• 首次为将接入 AI Agent 的代码仓库进行设置（claude-code-review、speckit 等）
• 已有 Agent，但缺少架构文档的代码仓库——#1585 类 Bug
• 完成重大重构后，更新过时的文档
• 将代码仓库接入 fellowship-dev harness（目标：fellowship-dev/booster-pack）

设计原则

“给 Agent 一张地图，而不是一份长达 1,000 页的说明书。”

CLAUDE.md 保持简短（约 100 行），充当目录，指向更深入的文档。 渐进式披露：Agent 先阅读概览，再深入查看所需的具体章节。 此技能根据代码仓库中已有的内容创建这张地图。

创建内容

文件	用途
ARCHITECTURE.md	主要架构决策和关键模式
QUALITY_SCORE.md	领域质量评级——由 entropy-check 技能更新
docs/code-structure.md	实际发现的模式（“X 的工作方式”）
docs/code-guidelines.md	黄金准则，由 hookshot 以机械方式强制执行
flowchad/	关键路径的流程定义存根
.claude/CLAUDE.md	更新后的目录，指向所有文档

已存在的文件会更新（合并），不会整体覆盖。

---

说明

0. 确认代码仓库

# Get repo identity
git remote get-url origin
git rev-parse --show-toplevel

# Capture these for the rest of the skill
REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename $(git remote get-url origin) .git)

询问（或根据 package.json / Gemfile / pyproject.toml 推断）：

• 使用的语言/框架是什么？（Rails、Next.js、Python 等）
• 主要领域是什么？（电子商务、内容、身份验证等）

如果代码仓库有 README，请阅读并提取：用途、关键概念、技术栈。

1. 发现阶段

扫描代码仓库结构，了解现有内容：

# Top-level structure
ls -la $REPO_ROOT

# Source directories (skip node_modules, .git, vendor, tmp)
find $REPO_ROOT -maxdepth 3 -type d \
  ! -path '*/.git/*' \
  ! -path '*/node_modules/*' \
  ! -path '*/vendor/*' \
  ! -path '*/tmp/*' \
  ! -path '*/.next/*' \
  ! -path '*/dist/*' \
  | sort

# Key files
ls $REPO_ROOT/docs/ 2>/dev/null || echo "No docs/"
ls $REPO_ROOT/.claude/ 2>/dev/null || echo "No .claude/"
ls $REPO_ROOT/flowchad/ 2>/dev/null || echo "No flowchad/"
ls $REPO_ROOT/.github/workflows/ 2>/dev/null || echo "No workflows"

# Detect framework
ls $REPO_ROOT/Gemfile $REPO_ROOT/package.json $REPO_ROOT/pyproject.toml \
   $REPO_ROOT/go.mod $REPO_ROOT/Cargo.toml 2>/dev/null

根据目录结构推断领域。 示例：

• app/models/ + app/controllers/ → Rails MVC 领域
• src/components/ + src/pages/ → Next.js 前端领域
• services/ + workers/ → 面向服务的领域
• lib/ + spec/ → 库模式

记录：推断出的领域列表（例如：内容模型、身份验证、API、前端路由、后台任务）。

2. 模式发现

针对每个推断出的领域，搜索关键模式：

# Entry points (routes, controllers, resolvers)
grep -r "def " $REPO_ROOT/app/controllers/ --include="*.rb" -l 2>/dev/null | head -10
grep -r "export default" $REPO_ROOT/src/pages/ --include="*.tsx" -l 2>/dev/null | head -10

# Key abstractions (base classes, mixins, concerns)
grep -rl "class.*Base\|module.*Concern\|extends.*Component" \
  $REPO_ROOT/app $REPO_ROOT/lib $REPO_ROOT/src 2>/dev/null | head -10

# Shared utilities (helpers, services)
ls $REPO_ROOT/app/services/ $REPO_ROOT/lib/ $REPO_ROOT/src/lib/ 2>/dev/null

# Critical paths (auth, payment, data mutations)
grep -rl "authenticate\|authorize\|payment\|stripe\|checkout\|redirect" \
  $REPO_ROOT/app $REPO_ROOT/src 2>/dev/null | head -20

阅读每个领域中 2-3 个关键文件，了解实际模式。不要仅依赖文件名。

识别关键路径——发生 Bug 会对用户造成重大损害的流程：

• 身份验证流程（登录、令牌刷新、权限检查）
• 数据变更流程（创建/更新/删除及其副作用）
• 支付流程（如适用）
• 外部 API 集成（Webhook、第三方调用）

3. 编写 ARCHITECTURE.md

创建或更新 $REPO_ROOT/ARCHITECTURE.md：

# Architecture — {REPO_NAME}

> Last updated: {DATE} by setup-harness

## Overview

{1-2 paragraphs: what this system does, its primary responsibility, who uses it}

## Tech Stack

| Layer | Technology | Notes |
|-------|-----------|-------|
| Runtime | {e.g., Ruby 3.2 / Rails 7} | |
| Frontend | {e.g., Next.js 14 / React} | |
| Database | {e.g., PostgreSQL 15} | |
| Background | {e.g., Sidekiq / Que} | |
| Auth | {e.g., Devise + JWT} | |

## Domains

{For each inferred domain:}

### {Domain Name}

**Files:** `{primary directory path}`

**Pattern:** {1-2 sentences describing how this domain works, with actual file/class names}

**Critical paths:**
- {Path name}: `{entry point}` → `{key step}` → `{outcome}`

**Known gotchas:**
- {Any patterns that are non-obvious or commonly misunderstood}

## Architectural Decisions

{Document any non-obvious decisions found during scan. Leave this section for humans to fill in if nothing is discovered.}

### Decision: {Short name}
- **Context:** {What problem this solves}
- **Decision:** {What was chosen}
- **Consequences:** {Trade-offs}

## Agent Guidance

When modifying code in this repo:
1. Read the relevant domain section above before touching files in that directory
2. Check `docs/code-structure.md` for how the pattern works
3. Check `docs/code-guidelines.md` for rules that must be followed
4. Check `QUALITY_SCORE.md` to understand domain health

> If you are about to write code that looks like it already exists — it probably does. Search first.

根据实际发现的内容填充所有章节。最终文件中不得使用 {placeholder} 文本。

4. 编写 docs/code-structure.md

创建或更新 $REPO_ROOT/docs/code-structure.md。

此文档必须记录真实模式，而不是目录清单。 针对每个领域，结合实际代码引用说明模式的工作方式。

模板：

# Code Structure — {REPO_NAME}

> Last updated: {DATE} by setup-harness. Update this file when patterns change.

## How to Read This Doc

Each section covers a domain. For each domain:
- **The pattern** explains the standard way things work
- **The entry point** is where to start reading
- **Don't repeat** calls out existing utilities to use instead of reimplementing

---

## {Domain 1 Name}

**Directory:** `{path}`

### The Pattern

{Explain the pattern in plain English. Example:}

> Controllers in `app/controllers/` inherit from `ApplicationController`. Auth is handled
> by `before_action :authenticate_user!` — never roll your own. Model validations live
> on the model, not the controller. Service objects in `app/services/` handle business
> logic that doesn't belong on a model.

### Entry Points

| Concern | Where to look |
|---------|--------------|
| Routes | `config/routes.rb` |
| Auth | `app/controllers/application_controller.rb` |
| User model | `app/models/user.rb` |

### Don't Repeat

- **Redirects**: Use `check_redirect` in `lib/redirect_service.rb`, not a new conditional
- **Permissions**: Use `policy` objects in `app/policies/`, not inline `if current_user.admin?`
- **Email**: Use `UserMailer` in `app/mailers/`, not direct `ActionMailer::Base`

---

{Repeat for each domain}

## Cross-Cutting Concerns

### Error Handling

{How errors are handled across the app}

### Logging

{What gets logged, where, and how}

### Testing

{Testing strategy — unit/integration split, key helpers, fixture approach}

阅读实际源文件，在“不要重复造轮子”章节中填入真实可用的工具。这是解决 #1585 类 Bug 的主要方法。

5. 编写 docs/code-guidelines.md

创建或更新 $REPO_ROOT/docs/code-guidelines.md：

# Code Guidelines — {REPO_NAME}

> These are enforced by hookshot hooks and checked by entropy-check scans.
> Adding a new rule here? Run `/hookshot` to generate enforcement hooks.

## Golden Rules

These rules are never negotiated. Violations get flagged in PR review.

1. **Search before you implement.** Before writing a new utility, service, or helper, grep
   for existing implementations. The codebase has patterns — use them.

2. **Domain boundaries are hard.** {e.g., "Controllers do not query the database directly.
   Use service objects. Models do not call external APIs."} 

3. **{Rule 3}** — infer from codebase patterns

4. **{Rule 4}** — infer from codebase patterns

## Per-Domain Rules

### {Domain}

- {Specific rule for this domain, inferred from code patterns}
- {Another rule}

## Patterns That Look Wrong But Are Correct

{Document any patterns that look like bugs but are intentional. Prevents agents from
"fixing" working code.}

## Patterns That Look Right But Are Wrong

{Document common mistakes — especially ones that pass tests but fail in production.}

## When in Doubt

1. Read the relevant section in `docs/code-structure.md`
2. Search for an existing implementation
3. Check `ARCHITECTURE.md` for architectural constraints
4. Ask in a comment rather than guessing

根据代码库推断规则。如果发现基类，请记录“继承 X，而不是使用原始实现”。如果发现服务模式，请记录“业务逻辑使用服务”。具体说明。

6. 编写 QUALITY_SCORE.md

创建 $REPO_ROOT/QUALITY_SCORE.md：

# Quality Score — {REPO_NAME}

> Maintained by the entropy-check skill. Do not edit manually.
> Grade scale: A=all signals green, B=1 signal missing, C=2 missing, D=3+, F=no docs

Last audit: {DATE} (initial scaffold by setup-harness)

## Domains

| Domain | Grade | Last audit | Notes |
|--------|-------|------------|-------|
{For each inferred domain:}
| {Domain} | C | {DATE} | Initial scaffold — needs human review |

## Grade Signals (per domain)

Each domain is graded on:
- [ ] docs/code-structure.md covers this domain
- [ ] FlowChad flows defined for critical paths
- [ ] Last commit date vs last doc update (staleness ≤30 days)
- [ ] Open issues tagged to domain (≤3 open)
- [ ] Test coverage available (if measurable)

## History

| Date | Action | Result |
|------|--------|--------|
| {DATE} | Initial scaffold by setup-harness | {N} domains discovered |

7. 创建 FlowChad 存根

为发现的每条关键路径：

mkdir -p $REPO_ROOT/flowchad

针对每条关键路径，创建 $REPO_ROOT/flowchad/{path-name}.yml：

# FlowChad Flow Definition — {Path Name}
# Generated by setup-harness on {DATE}
# TODO: Validate this flow against actual code and fill in edge cases

name: {path-name}
description: "{1-line description of what this flow does}"
domain: "{domain name}"
criticality: high  # high | medium | low

steps:
  - id: entry
    label: "{Entry point — e.g., POST /sessions}"
    file: "{entry file path}"
    notes: "TODO: verify"

  - id: step-2
    label: "{Next step}"
    file: "TODO"
    notes: "TODO: fill in from code"

  # Add more steps based on code discovery

edges:
  - from: entry
    to: step-2
    condition: "happy path"

  # Add error/edge paths

open_questions:
  - "TODO: What happens if {edge case}?"

为以下流程创建存根：身份验证流程、主要数据变更流程，以及发现的任何其他关键路径。

8. 更新 .claude/CLAUDE.md

如果现有 .claude/CLAUDE.md，请先阅读。添加或更新“知识层”部分：

## Knowledge Layer

This repo has a knowledge layer for agents. Read before modifying:

| Doc | What it covers |
|-----|---------------|
| [ARCHITECTURE.md](../ARCHITECTURE.md) | Tech stack, domains, architectural decisions |
| [QUALITY_SCORE.md](../QUALITY_SCORE.md) | Domain health grades |
| [docs/code-structure.md](../docs/code-structure.md) | How patterns work, what NOT to reimplement |
| [docs/code-guidelines.md](../docs/code-guidelines.md) | Rules enforced by hooks |
| [flowchad/](../flowchad/) | Critical path flow definitions |

**Rule #1:** Before modifying code in a domain, read its section in `docs/code-structure.md`.
**Rule #2:** Before writing a new utility/service/helper, search for an existing one.

确保 CLAUDE.md 总行数少于 150 行。如果超过，请将内容移至相应的专用文档。

9. 运行 Hookshot

最后一步，运行 hookshot，根据刚创建的文档生成强制执行钩子：

请遵循 hookshot SKILL.md 中的完整说明（.claude/skills/hookshot/SKILL.md）。这将生成：

• .claude/doc-coverage.json — 覆盖映射
• scripts/check-docs.sh（或 .claude/check-docs.sh）— 钩子脚本
• .claude/settings.json hooks — PreToolUse 接线配置
• docs/hooks.md — 面向用户的钩子文档

如果未安装 hookshot，请跳过此步骤，并在总结报告中注明需要手动跟进。

10. 总结报告

输出：

## Setup Harness Complete: {REPO_NAME}

### Discovered
- {N} domains: {list}
- {N} critical paths: {list}
- Tech stack: {stack}

### Created
- ✅ ARCHITECTURE.md ({N} domains documented)
- ✅ QUALITY_SCORE.md ({N} domains graded)
- ✅ docs/code-structure.md (real patterns, not placeholders)
- ✅ docs/code-guidelines.md ({N} golden rules)
- ✅ flowchad/{N} flow stubs
- ✅ .claude/CLAUDE.md updated (table of contents)

### Hookshot
- {✅ Hookshot ran successfully — hooks generated / ⚠️ Hookshot not installed — run manually}
- .claude/doc-coverage.json: {N} entries
- docs/hooks.md: {generated / skipped}

### Grades (initial)
{Grade table from QUALITY_SCORE.md}

### Manual Next Steps
- [ ] Review ARCHITECTURE.md — add architectural decisions the scan missed
- [ ] Review docs/code-structure.md — verify "Don't Repeat" entries are current
- [ ] Complete flowchad/ stubs with actual edge cases
- [ ] Run `/entropy-check` to re-grade after manual review