@walwal-harness/cli 1.0.0 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
ADDED
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# walwal-harness
|
|
2
|
+
|
|
3
|
+
**AI 에이전트를 위한 프로덕션 하네스 엔지니어링 프레임워크**
|
|
4
|
+
|
|
5
|
+
> Solo: 20min/$9 (broken) → Harness: 6hr/$200 (fully functional)
|
|
6
|
+
> — [Anthropic Engineering Blog](https://www.anthropic.com/engineering/harness-design-long-running-apps)
|
|
7
|
+
|
|
8
|
+
같은 AI 모델이라도 **하네스 설계에 따라 결과물 품질이 극적으로 달라집니다.** walwal-harness는 Anthropic이 제안한 하네스 엔지니어링 패턴을 설치 한 번으로 즉시 사용할 수 있게 패키징한 프레임워크입니다.
|
|
9
|
+
|
|
10
|
+
## 무엇을 하는가
|
|
11
|
+
|
|
12
|
+
6개의 전문화된 AI 에이전트가 **역할 분리 + 피드백 루프**로 소프트웨어를 만듭니다:
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
"하네스 엔지니어링 시작"
|
|
16
|
+
│
|
|
17
|
+
▼
|
|
18
|
+
DISPATCHER ─── 요청 분석 ─── 파이프라인 자동 선택
|
|
19
|
+
│
|
|
20
|
+
┌────┴────┬──────────┐
|
|
21
|
+
▼ ▼ ▼
|
|
22
|
+
FULLSTACK FE-ONLY BE-ONLY
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### FULLSTACK (신규 프로젝트)
|
|
26
|
+
```
|
|
27
|
+
Planner → Generator-BE → Generator-FE → Evaluator-Func → Evaluator-Visual
|
|
28
|
+
│ FAIL
|
|
29
|
+
└──→ 재작업 (max 10회)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### FE-ONLY (기존 API에 프론트엔드 연동)
|
|
33
|
+
```
|
|
34
|
+
Planner(light) → Generator-FE → Evaluator-Func → Evaluator-Visual
|
|
35
|
+
└─ OpenAPI → api-contract.json 자동 변환
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### BE-ONLY (기존 서버에 백엔드 기능 추가)
|
|
39
|
+
```
|
|
40
|
+
Planner → Generator-BE → Evaluator-Func(API-only)
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## 설치
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm install @walwal-harness/cli
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
설치 시 자동으로:
|
|
50
|
+
- `.harness/` 디렉토리 스캐폴딩 (actions, archive, gotchas)
|
|
51
|
+
- `.claude/skills/` 에 6개 에이전트 스킬 설치
|
|
52
|
+
- `AGENTS.md` 생성 + `CLAUDE.md` 심볼릭 링크
|
|
53
|
+
- 기존 프로젝트면 구조 스캔 → IA-MAP 자동 생성
|
|
54
|
+
|
|
55
|
+
## 사용법
|
|
56
|
+
|
|
57
|
+
Claude Code에서:
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
> 하네스 엔지니어링 시작
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
이 한 마디로 Dispatcher가 실행되어:
|
|
64
|
+
1. 프로젝트 초기화 상태 확인 (빈 프로젝트 / 기존 프로젝트 자동 감지)
|
|
65
|
+
2. 사용자 요청 분석 → 파이프라인 선택
|
|
66
|
+
3. 순차적으로 에이전트 실행
|
|
67
|
+
|
|
68
|
+
## 6개 에이전트
|
|
69
|
+
|
|
70
|
+
| 에이전트 | 역할 | SKILL |
|
|
71
|
+
|----------|------|-------|
|
|
72
|
+
| **Dispatcher** | 파이프라인 선택 + Gotcha 관리 | `harness-dispatcher` |
|
|
73
|
+
| **Planner** | 제품 사양 + API 계약서 + IA-MAP 설계 | `harness-planner` |
|
|
74
|
+
| **Generator-Backend** | NestJS MSA 구현 (Gateway + Microservices) | `harness-generator-backend` |
|
|
75
|
+
| **Generator-Frontend** | React/Next.js UI + API 연동 | `harness-generator-frontend` |
|
|
76
|
+
| **Evaluator-Functional** | Playwright E2E 기능 검증 + IA 구조 검증 | `harness-evaluator-functional` |
|
|
77
|
+
| **Evaluator-Visual** | 디자인 일관성, 반응형, 접근성, AI슬롭 감지 | `harness-evaluator-visual` |
|
|
78
|
+
|
|
79
|
+
## 핵심 기능
|
|
80
|
+
|
|
81
|
+
### API Contract — 진실의 원천
|
|
82
|
+
|
|
83
|
+
`api-contract.json`이 Frontend ↔ Gateway ↔ Microservices 간 유일한 계약서입니다. Planner만 수정 가능하며, Generator-BE는 이를 구현하고, Generator-FE는 이를 소비합니다.
|
|
84
|
+
|
|
85
|
+
### AGENTS.md — 에이전트 불문 범용 컨텍스트
|
|
86
|
+
|
|
87
|
+
모든 AI 에이전트(Claude, Cursor, Copilot, Windsurf)가 읽을 수 있는 공통 진입점입니다. 1차원 IA-MAP으로 폴더별 책임과 소유 에이전트를 명시합니다.
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
├── apps/gateway/ # [BE] API Gateway → Generator-Backend
|
|
91
|
+
├── apps/service-a/ # [BE] Microservice → Generator-Backend
|
|
92
|
+
├── apps/web/ # [FE] Frontend App → Generator-Frontend
|
|
93
|
+
└── .harness/ # [HARNESS] 하네스 시스템 → Planner
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Gotcha 시스템 — 실수를 반복하지 않는 에이전트
|
|
97
|
+
|
|
98
|
+
사용자가 에이전트의 실수를 지적하면 Dispatcher가 자동으로 감지하여 해당 에이전트의 gotchas 파일에 기록합니다. 이후 세션에서 에이전트는 시작 시 자신의 gotchas를 읽고 같은 실수를 반복하지 않습니다.
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
사용자: "API 응답에 created_at은 ISO 8601로 반환해야 해"
|
|
102
|
+
→ Dispatcher: generator-backend.md에 [G-001] 기록
|
|
103
|
+
→ Generator-BE 다음 세션: gotchas 읽기 → 같은 실수 방지
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### IA Structure Compliance — Step 0 Gate
|
|
107
|
+
|
|
108
|
+
Evaluator는 기능 테스트 전에 AGENTS.md의 IA-MAP과 실제 폴더 구조를 대조합니다. 경로 누락이나 소유권 침범이 발견되면 **기능 테스트 없이 즉시 FAIL**합니다.
|
|
109
|
+
|
|
110
|
+
### 브라운필드 지원
|
|
111
|
+
|
|
112
|
+
기존 프로젝트에 설치하면:
|
|
113
|
+
- `scan-project.sh`가 Tech Stack, 폴더 구조, 기존 CLAUDE.md를 자동 스캔
|
|
114
|
+
- 기존 CLAUDE.md 규칙을 "Preserved Rules" 섹션으로 이관
|
|
115
|
+
- 원본은 `.harness/archive/pre-harness-backup/`에 백업
|
|
116
|
+
|
|
117
|
+
## 디렉토리 구조
|
|
118
|
+
|
|
119
|
+
설치 후 프로젝트에 생성되는 구조:
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
your-project/
|
|
123
|
+
├── AGENTS.md # 에이전트 공통 컨텍스트 (Planner 관리)
|
|
124
|
+
├── CLAUDE.md → AGENTS.md # 심볼릭 링크
|
|
125
|
+
├── .harness/
|
|
126
|
+
│ ├── config.json # 하네스 설정
|
|
127
|
+
│ ├── progress.txt # 세션 간 상태 전달
|
|
128
|
+
│ ├── gotchas/ # 에이전트별 실수 기록
|
|
129
|
+
│ │ ├── planner.md
|
|
130
|
+
│ │ ├── generator-backend.md
|
|
131
|
+
│ │ ├── generator-frontend.md
|
|
132
|
+
│ │ ├── evaluator-functional.md
|
|
133
|
+
│ │ └── evaluator-visual.md
|
|
134
|
+
│ ├── actions/ # 활성 스프린트 문서
|
|
135
|
+
│ │ ├── pipeline.json
|
|
136
|
+
│ │ ├── plan.md
|
|
137
|
+
│ │ ├── feature-list.json
|
|
138
|
+
│ │ ├── api-contract.json
|
|
139
|
+
│ │ └── sprint-contract.md
|
|
140
|
+
│ └── archive/ # 완료 스프린트 보관 (불변)
|
|
141
|
+
│ └── sprint-NNN/
|
|
142
|
+
└── .claude/skills/ # Claude Code 스킬
|
|
143
|
+
├── harness-dispatcher/
|
|
144
|
+
├── harness-planner/
|
|
145
|
+
├── harness-generator-backend/
|
|
146
|
+
├── harness-generator-frontend/
|
|
147
|
+
├── harness-evaluator-functional/
|
|
148
|
+
└── harness-evaluator-visual/
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Tech Stack
|
|
152
|
+
|
|
153
|
+
| 영역 | 기술 |
|
|
154
|
+
|------|------|
|
|
155
|
+
| Backend | NestJS (TypeScript) + MSA |
|
|
156
|
+
| Frontend | React 또는 Next.js (TypeScript) |
|
|
157
|
+
| Styling | Tailwind CSS |
|
|
158
|
+
| E2E Testing | Playwright MCP |
|
|
159
|
+
| Unit Testing | Jest (BE) + Vitest (FE) |
|
|
160
|
+
| Database | PostgreSQL / SQLite |
|
|
161
|
+
|
|
162
|
+
## Playwright MCP 설정
|
|
163
|
+
|
|
164
|
+
Evaluator가 브라우저 테스트를 수행하려면 Playwright MCP가 필요합니다. `~/.mcp.json`에 추가:
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"mcpServers": {
|
|
169
|
+
"playwright": {
|
|
170
|
+
"command": "npx",
|
|
171
|
+
"args": ["-y", "@playwright/mcp@latest", "--headless", "--caps", "vision"]
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## 참고
|
|
178
|
+
|
|
179
|
+
- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
|
|
180
|
+
- [Anthropic: Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
|
|
181
|
+
- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
|
|
182
|
+
- [Skill Authoring Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
|
|
183
|
+
|
|
184
|
+
## License
|
|
185
|
+
|
|
186
|
+
MIT
|
|
@@ -74,9 +74,9 @@ Planner → Gen-BE → Eval-Func(API-only) → Archive
|
|
|
74
74
|
### 공통 — 실패 시 루프
|
|
75
75
|
|
|
76
76
|
```
|
|
77
|
-
Eval-Func FAIL → failure_location에 따라 Gen-BE 또는 Gen-FE 재작업 (max
|
|
78
|
-
Eval-Visual FAIL → Gen-FE 재작업 (max
|
|
79
|
-
|
|
77
|
+
Eval-Func FAIL → failure_location에 따라 Gen-BE 또는 Gen-FE 재작업 (max 10회)
|
|
78
|
+
Eval-Visual FAIL → Gen-FE 재작업 (max 10회)
|
|
79
|
+
10회 초과 → 사용자 개입 요청
|
|
80
80
|
```
|
|
81
81
|
|
|
82
82
|
## 수동 프롬프트 실행 방법
|
package/package.json
CHANGED