setup-harness

Setup Harness

あらゆるリポジトリのナレッジレイヤーをスキャフォールドします。スキャンし、推測し、内容を反映します。

npx でインストール：

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

使用する場面

• AI エージェント（claude-code-review、speckit など）を導入するリポジトリの初回セットアップ
• エージェントは導入済みでも、アーキテクチャのドキュメントがないリポジトリ — #1585 クラスのバグ
• 大規模な再構成の後、古くなったドキュメントを更新する場合
• リポジトリを fellowship-dev ハーネスにオンボーディングする場合（対象：fellowship-dev/booster-pack）

設計原則

「エージェントには、1,000 ページの取扱説明書ではなく地図を渡しましょう。」

CLAUDE.md は短く（約 100 行）保ち、より詳細なドキュメントを示す目次として機能させます。 段階的な開示により、エージェントはまず概要を読み、必要なセクションを掘り下げます。 このスキルは、リポジトリにすでに存在する情報をもとに、その地図を作成します。

作成されるもの

ファイル	目的
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 など）
• 主なドメインは何ですか？（e コマース、コンテンツ、認証など）

リポジトリに 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. パターンの発見

推測した各ドメインについて、重要なパターンを grep で探します。

# 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 個読み、実際のパターンを把握します。ファイル名だけに頼らないでください。

重要な処理経路 — バグによってユーザーに重大な被害が生じる一連の処理 — を特定します。

• 認証フロー（ログイン、トークン更新、権限チェック）
• データ変更フロー（副作用を伴う作成／更新／削除）
• 決済フロー（該当する場合）
• 外部 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 クラスのバグに対する主要な修正です。

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」セクションを追加または更新します。

## 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