@uzysjung/agent-harness 26.156.0 → 26.158.0
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.ko.md +66 -48
- package/README.md +64 -44
- package/dist/{chunk-PPJUFG53.js → chunk-HHCNPPGS.js} +5 -2
- package/dist/chunk-HHCNPPGS.js.map +1 -0
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/trust-tier-drift.js +1 -1
- package/package.json +1 -1
- package/templates/rules/test-policy.md +13 -1
- package/templates/skills/audit-harness-fit/references/audit.md +18 -0
- package/templates/skills/audit-harness-fit/references/verification.md +15 -0
- package/templates/skills/recurrence-prevention/SKILL.md +36 -29
- package/dist/chunk-PPJUFG53.js.map +0 -1
package/README.ko.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# uzys-agent-harness
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
AI 코딩 도구에 꼭 필요한 룰·훅·스킬만 남기고 나머지는 걷어낸다. 위저드 한 번으로 내 스택에 맞게 검증된 묶음을 Claude Code · Codex · OpenCode · Antigravity 에 프로젝트 범위로 설치한다.
|
|
4
4
|
|
|
5
5
|
[](LICENSE)
|
|
6
|
-
[](https://github.com/uzysjung/uzys-agent-harness/
|
|
6
|
+
[](https://github.com/uzysjung/uzys-agent-harness/tags)
|
|
7
7
|
[](https://github.com/uzysjung/uzys-agent-harness/actions)
|
|
8
8
|
|
|
9
9
|
|
|
@@ -14,6 +14,8 @@
|
|
|
14
14
|
|
|
15
15
|
## 설치
|
|
16
16
|
|
|
17
|
+
Node 20 이상이 필요하다. Claude Code 플러그인을 쓸 거라면 `claude` 명령이 PATH 에 있어야 한다 — 없으면 플러그인 설치는 경고만 남기고 건너뛴다.
|
|
18
|
+
|
|
17
19
|
```bash
|
|
18
20
|
npx -y @uzysjung/agent-harness
|
|
19
21
|
```
|
|
@@ -21,94 +23,110 @@ npx -y @uzysjung/agent-harness
|
|
|
21
23
|
위저드가 6단계로 안내한다:
|
|
22
24
|
|
|
23
25
|
```
|
|
24
|
-
1/6 Tracks
|
|
25
|
-
2/6 CLI claude / codex / opencode / antigravity
|
|
26
|
-
3/6 Install items 미리
|
|
27
|
-
4/6 Scope Project
|
|
28
|
-
5/6 Confirm
|
|
26
|
+
1/6 Tracks 무엇을 만드는지 고른다
|
|
27
|
+
2/6 CLI claude / codex / opencode / antigravity — 여러 개 가능
|
|
28
|
+
3/6 Install items 트랙에 맞는 항목이 미리 체크되어 있다. 원치 않는 것은 해제
|
|
29
|
+
4/6 Scope Project(기본값) 또는 Global
|
|
30
|
+
5/6 Confirm 요약과 함께, 이 선택이 매 세션에 얹는 컨텍스트 크기를 보여 준다
|
|
29
31
|
6/6 Installing
|
|
30
32
|
```
|
|
31
33
|
|
|
32
|
-
설치가 끝나면 CLI 를
|
|
34
|
+
설치가 끝나면 프로젝트에서 CLI 를 연다 — 룰과 스킬, 그리고 Claude Code 에서는 훅까지 바로 적용된다:
|
|
33
35
|
|
|
34
36
|
```bash
|
|
35
37
|
claude # 또는 codex / opencode / agy
|
|
36
38
|
```
|
|
37
39
|
|
|
38
|
-
|
|
40
|
+
**첫 세션에서 할 일.** 설치가 끝나면 *내 프로젝트* 이야기를 채울 빈칸이 있는 `CLAUDE.md`(또는 `AGENTS.md`)가 생긴다. 에이전트에게 `audit-harness-fit` 스킬을 한 번 돌리라고 하면 저장소를 읽고 그 빈칸을 근거로 채운다. 그 뒤로는 하네스가 이 프로젝트에 아직 맞는지 점검할 때 같은 스킬을 쓴다. "내 스택을 인터뷰해 주는" 단계는 따로 없다 — 스택은 1단계에서 이미 골랐고, 나머지는 이 스킬이 코드를 읽어 채운다.
|
|
39
41
|
|
|
40
|
-
|
|
42
|
+
위저드는 터미널이 필요하다. CI·컨테이너·온보딩 스크립트에서는 플래그 형식을 쓴다. 필수 플래그는 `install --track <name>` 하나다 — [비대화형 설치](docs/USAGE.md#non-interactive-install) 참고.
|
|
41
43
|
|
|
42
|
-
|
|
44
|
+
### 설치 경로는 둘이다
|
|
43
45
|
|
|
44
|
-
|
|
46
|
+
| 원하는 것 | 방법 |
|
|
47
|
+
|---|---|
|
|
48
|
+
| 하네스 전체 — 룰·훅·에이전트와 내 스택에 맞는 스킬을 트랙 단위로 | 위의 위저드 |
|
|
49
|
+
| 스킬 하나만 — 하네스도 트랙도 없이 | `npx skills add uzysjung/uzys-agent-harness --skill <id> -a claude-code` |
|
|
45
50
|
|
|
46
|
-
|
|
47
|
-
npx -y @uzysjung/agent-harness list # 이 프로젝트에 깔린 것
|
|
48
|
-
npx -y @uzysjung/agent-harness update # 현재 릴리즈로 갱신
|
|
49
|
-
npx -y @uzysjung/agent-harness uninstall # 무엇을 뺄지 고른다
|
|
50
|
-
```
|
|
51
|
+
이 저장소가 배포하는 모든 스킬은 [skills CLI](https://github.com/vercel-labs/skills) 로 하나씩 받을 수 있다. `npx skills add uzysjung/uzys-agent-harness --list` 로 id 목록을 본다. 설치 프로그램이 복사하는 것과 같은 파일(`references/` 포함)을 받고, 같은 명령을 다시 돌리면 갱신된다([자세히](docs/USAGE.md#one-skill-without-the-harness)). [skills.sh/uzysjung/uzys-agent-harness](https://skills.sh/uzysjung/uzys-agent-harness) 에도 올라가 있다.
|
|
51
52
|
|
|
52
|
-
|
|
53
|
-
것만 되돌리고, 글로벌 자산과 `.mcp.json` 같은 `.claude/` 밖 파일은 지우는 대신 경로를
|
|
54
|
-
*출력한다* — 사용자 내용이 섞인 파일은 기계적으로 고치지 않는다. 설치 화면에서 체크를 풀어도
|
|
55
|
-
제거되지 않으며, 제거는 오직 이 명령에서만 일어난다. 자세한 내용은
|
|
56
|
-
[uninstall](docs/USAGE.md#uninstall-v26640) 참고.
|
|
53
|
+
## 철학 — 필요한 틀만 남겨 AI 의 개발 생산성을 높인다
|
|
57
54
|
|
|
58
|
-
|
|
55
|
+
AI 코딩 도구에 룰과 스킬을 쌓을수록 좋아지는 게 아니다. 항상 읽히는 지시문은 전부 매 세션의 비용이고, 최신 모델이 이미 잘하는 일을 지시하면 속도만 깎인다. 이 하네스는 반대 방향에서 출발한다 — **모델이 실수할 것 같은 곳에만 원칙을 두고, 모델이 좋아지면 그것도 걷어낸다.**
|
|
59
56
|
|
|
60
|
-
|
|
57
|
+
- **"하지 마라 · 반드시 해라"는 최신 모델의 성능을 깎는다.** 금지문과 의무문이 쌓인 지시문은 모델이 판단할 자리를 없앤다. 상황이 지시문과 조금만 달라도 모델은 멈칫하거나 엉뚱하게 우회하고, 가드가 가드를 검사하기 시작하면 개발은 느려지는데 품질은 그대로다. 그래서 이 하네스는 지시를 "무엇이 참이어야 하는가"(완료 조건 · 불변식 · 경계)로 쓰고 "어떻게"는 모델에게 맡긴다. 금지문은 되돌릴 수 없는 손상 — 시크릿과 공유 이력 — 에만 남기고, 그것조차 문장이 아니라 장치가 막는다. `.env` 와 키 파일 편집은 훅이 막고, 기본 브랜치는 하네스가 적용을 도와주는 GitHub 룰셋이 지킨다. 이 방향은 취향이 아니라 실측에서 나왔다. 우리 룰 44문장 가운데 에이전트의 행동을 바꿨다고 관측된 것은 0건이었고, 사고를 실제로 잡은 것은 게이트·테스트·독립 리뷰어였다.
|
|
61
58
|
|
|
62
|
-
|
|
59
|
+
- **모델이 발전하면 스킬도 같이 개선된다.** 자산은 "이게 없으면 에이전트가 실제로 더 느리거나 더 틀린다"는 관측이 있을 때만 남는다. 근거가 없는 지시문은 상시 지시에서 빠져, 필요할 때만 불러오는 스킬이 되거나 아예 없어진다. 그래서 `update` 는 단순히 더 많은 것이 아니라 지금의 판단 — 무엇이 더해지고 무엇이 빠졌는가 — 을 가져온다.
|
|
63
60
|
|
|
64
|
-
|
|
61
|
+
- **`audit-harness-fit` 으로 계속 점검한다.** 설치 직후 한 번 돌리면 저장소를 읽어 프로젝트 맥락을 채운다. 나중에 돌리면 불필요한 질문, 반복되는 검사, 서로 모순되는 결정, 더 좋아진 모델에게는 필요 없는 절차를 찾아 수정안을 낸다. 하네스가 내 프로젝트에 맞는지는 설치할 때 정하는 게 아니라 쓰는 내내 묻는 질문이다.
|
|
65
62
|
|
|
66
|
-
-
|
|
63
|
+
- **속도와 품질은 맞바꾸는 게 아니다.** 되돌릴 수 없는 손상은 훅이 막고, 반복되는 실수는 짧은 룰이 잡고, 나머지는 모델에게 맡긴다. 검증은 "매번 전부"가 아니다 — 사용자에게 보이는 장면 하나가 완성될 때, 코드를 쓰지 않은 다른 에이전트가 실제로 실행해 본다. 목표는 가드를 늘리는 게 아니라 중요한 것을 가장 가볍게 지키는 방법이다.
|
|
67
64
|
|
|
68
|
-
-
|
|
65
|
+
- **만드는 서비스의 고객 관점에서 생각하고 설명한다.** 에이전트는 문제·변경·선택지를 파일명과 함수가 아니라 "사용자가 무엇을 하고 무엇을 보게 되는가"로 먼저 말한다(`user-centered-explanation`). 승인이 필요한 순간은 맥락 → 문제 → 선택지 → 추천 순서로 정리되어, 앞의 대화를 다시 읽지 않아도 결정할 수 있다.
|
|
69
66
|
|
|
70
|
-
|
|
67
|
+
이 다섯이 방향이고, 자산을 넣고 뺄 때의 첫 질문은 하나다 — **이게 사람이 AI 코딩 도구로 개발을 더 잘하게 만드는가.** 전문은 [docs/NORTH_STAR.md](docs/NORTH_STAR.md).
|
|
71
68
|
|
|
72
|
-
##
|
|
69
|
+
## 무엇을 얻는가
|
|
73
70
|
|
|
74
|
-
|
|
71
|
+
- **룰** — git 정책 · 변경 관리 · 문서 · 테스트 · 출하 · CLI 개발에 관한 짧은 파일 6개. 개발 트랙은 5개, `tooling` 과 `full` 은 여섯째까지, 비즈니스 트랙은 어느 프로젝트에나 해당하는 3개를 받는다.
|
|
72
|
+
- **훅** — Claude Code 에 2개. 하나는 세션 시작 때 스펙과 변경 이력을 읽어 오고, 하나는 `.env` · lock 파일 · 인증서 편집을 막는다. 이 둘째 훅이 하네스에서 유일하게 "안 된다"고 말하는 것이고, 막을 때마다 로그에 한 줄을 남긴다. Codex 는 세션 시작 훅만 받는다 — Codex 의 훅 API 는 파일 편집을 가로채지 못한다.
|
|
73
|
+
- **스킬** — 이 리포에서 직접 쓰고 관리하는 방법론 스킬과, 트랙이 부르는 스택 스킬. 4종은 모든 트랙에 포함된다(`north-star` · `objective-brief` · `gh-issue-workflow` · `audit-harness-fit`). 개발 트랙은 방법론 스킬 5종과 사고 대응 런북 하나를 더 받고, 스택이 있는 트랙에는 `find-skills` · `frontend-design` 과 스택별 스킬(예: `csr-supabase` 면 React · shadcn · Supabase · Postgres)이 설치된다. 번들 스킬 13종은 `--with` / `--without` 으로 이름을 지정할 수 있다.
|
|
74
|
+
- **에이전트** — 모든 트랙에 독립 `reviewer`, 개발 트랙에 `implementer`, `data-analyst` 와 `strategist` 는 그것을 쓰는 트랙에만.
|
|
75
|
+
- **작업 원칙 앵커** — CLI 가 매 세션 읽는 파일 하나. 내 `CLAUDE.md` 는 내 것으로 남고, 하네스는 import 한 줄만 얹고 나머지는 건드리지 않는다. 어느 파일이 누구 것인지: [docs/CONTEXT-FILES.md](docs/CONTEXT-FILES.md).
|
|
75
76
|
|
|
76
|
-
|
|
77
|
+
CLI 별로 도달하는 것:
|
|
77
78
|
|
|
78
|
-
|
|
79
|
+
| CLI | 룰 | 스킬 | 훅 | 플러그인 |
|
|
80
|
+
|---|---|---|---|---|
|
|
81
|
+
| Claude Code | ✓ | ✓ | ✓ | ✓ |
|
|
82
|
+
| Codex | ✓ (`AGENTS.md` 안에) | ✓ | 세션 시작만 | — |
|
|
83
|
+
| OpenCode | ✓ (`AGENTS.md` 안에) | ✓ | — | — |
|
|
84
|
+
| Antigravity | ✓ | ✓ | — | — |
|
|
79
85
|
|
|
80
|
-
|
|
86
|
+
플러그인은 Claude Code 자체 메커니즘이라 Claude 전용이다. 스킬과 룰은 같은 원본에서 네 CLI 에 맞게 변환되므로 서로 어긋날 일이 없다.
|
|
81
87
|
|
|
82
|
-
|
|
88
|
+
## 트랙
|
|
83
89
|
|
|
84
|
-
|
|
90
|
+
무엇을 만드느냐에 따라 12개 트랙으로 나눈다:
|
|
91
|
+
|
|
92
|
+
- **스택 미정** — `base`: 원칙 · 방법론 스킬 · 테스트 룰만, 스택 전용 자산 없음
|
|
85
93
|
- **프론트엔드 + 백엔드** — `csr-supabase` · `csr-fastify` · `csr-fastapi` · `ssr-nextjs` · `ssr-htmx`
|
|
86
94
|
- **데이터** — `data`
|
|
87
95
|
- **비즈니스** — `executive` · `project-management` · `growth-marketing`
|
|
88
|
-
- **메타** — `tooling
|
|
96
|
+
- **메타** — `tooling`: 앱 스택 없는 Bash · Markdown 프로젝트
|
|
89
97
|
- **전체** — `full`
|
|
90
98
|
|
|
91
|
-
|
|
99
|
+
트랙은 출발점이지 고정이 아니다. 미리 체크된 것은 3단계에서 전부 해제할 수 있고, 트랙을 여러 개 골라도 된다. [각 트랙이 무엇을 설치하는지 →](docs/TRACKS.md)
|
|
92
100
|
|
|
93
|
-
##
|
|
101
|
+
## 일상 명령
|
|
94
102
|
|
|
95
|
-
|
|
103
|
+
```bash
|
|
104
|
+
npx -y @uzysjung/agent-harness list # 이 프로젝트에 무엇이 깔렸나
|
|
105
|
+
npx -y @uzysjung/agent-harness update # 현재 릴리즈로 갱신
|
|
106
|
+
npx -y @uzysjung/agent-harness uninstall # 골라서 제거하거나 전부 제거
|
|
107
|
+
```
|
|
96
108
|
|
|
97
|
-
|
|
109
|
+
`update` 는 하네스가 설치한 파일을 갱신하고, 새 릴리즈에 추가된 스킬을 함께 설치하며, 재설치가 필요한 것(새 훅)은 그렇다고 알려 준다. 고르지 않은 CLI 를 설치하는 일은 없다. `update --only skills` 처럼 한 묶음만 갱신할 수 있다. `uninstall` 은 터미널에서 항목별로 묻고, `--dry-run` 으로 계획만 먼저 볼 수 있다.
|
|
98
110
|
|
|
99
|
-
|
|
111
|
+
**기존 프로젝트에도 안전하다.** 내가 고친 파일을 교체하기 전에 옆에 타임스탬프 백업을 만들고 경로를 출력한다. 내가 쓰거나 고친 것은 백업 없이 지우지 않는다. 기존 `.mcp.json` 서버는 교체가 아니라 병합된다. 자세한 내용: [기존 프로젝트에 설치하기](docs/USAGE.md#installing-into-an-existing-project).
|
|
100
112
|
|
|
101
|
-
|
|
113
|
+
**기본값은 프로젝트 범위다.** 4단계에서 Global 을 고르지 않는 한 `~/.codex/` · `~/.opencode/` · `~/.gemini/` · 전역 npm 에는 아무것도 쓰지 않는다. 예외는 Claude Code 플러그인 하나다 — `claude` CLI 는 어느 범위에서든 플러그인 캐시를 `~/.claude/plugins/` 아래 두고 프로젝트는 메타데이터로 구분한다. `.claude/` 밖에는 `.mcp.json`, `.gitignore` 몇 줄(그 파일이 있을 때), Supabase 트랙이면 `.env.example`, 그리고 설치 기록 `.uzys-agent-harness/` 를 쓴다 — 전체 목록은 [하네스가 쓰는 파일](docs/USAGE.md#what-the-harness-writes).
|
|
102
114
|
|
|
103
|
-
|
|
115
|
+
## 검증
|
|
104
116
|
|
|
105
|
-
|
|
117
|
+
외부 자산은 GitHub star 1,000개 이상, 보관(archived) 처리되지 않음, 설치 명령을 격리 환경에서 실제로 실행해 확인함 — 이 셋을 만족할 때 **vetted** 다. 매월 CI 두 개가 star 와 설치 경로를 다시 검사한다. vetted 는 라인 단위 보안 감사가 **아니고**, 자산 내용의 prompt injection 스캔도 하지 않는다. npm · npx 자산은 버전을 고정하고, plugin · skill 자산은 upstream HEAD 를 따른다.
|
|
106
118
|
|
|
107
|
-
|
|
119
|
+
3단계에서 `★ official` 은 Anthropic 공식 마켓플레이스와 이 하네스 자체 자산, `⚠ experimental` 은 star 1,000 미만 자산이다 — 미리 체크되지 않으며 직접 골라야만 설치된다. vetted 자산은 배지가 없다. 등급은 정보를 줄 뿐 설치를 막지 않는다. 설치한 자산은 다른 서드파티 의존성과 똑같이 다룬다: [SECURITY.md](SECURITY.md).
|
|
108
120
|
|
|
109
|
-
|
|
121
|
+
## 문서
|
|
110
122
|
|
|
111
|
-
|
|
123
|
+
- [사용 가이드](docs/USAGE.md) — 설치 플래그 · 범위 · update · uninstall · CLI 별 상세 · 어디에 무엇을 쓰는가
|
|
124
|
+
- [트랙](docs/TRACKS.md) — 트랙별로 미리 체크되는 것
|
|
125
|
+
- [호환성 매트릭스](docs/COMPATIBILITY.md) — 자산 전체의 설치 방식 · 지원 CLI · 검증 방법
|
|
126
|
+
- [어느 파일이 누구 것인가](docs/CONTEXT-FILES.md) — `CLAUDE.md` · 앵커 · `AGENTS.md` 와 나머지 컨텍스트 파일
|
|
127
|
+
- [워크플로 가이드](docs/WORKFLOWS.md) — 선택 설치 워크플로 비교와, 그게 필요 없는 경우
|
|
128
|
+
- [보안](SECURITY.md) — 검증이 보장하는 것과 아닌 것, 제보 방법
|
|
129
|
+
- [북극성](docs/NORTH_STAR.md) · [결정 기록](docs/decisions/) — 하네스가 왜 이런 모양인가
|
|
112
130
|
|
|
113
131
|
## License
|
|
114
132
|
|
package/README.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# uzys-agent-harness
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Give your AI coding tool the few rules, hooks, and skills it actually needs — and nothing it doesn't. One wizard installs a vetted set for your stack into Claude Code, Codex, OpenCode, or Antigravity, scoped to your project.
|
|
4
4
|
|
|
5
5
|
[](LICENSE)
|
|
6
|
-
[](https://github.com/uzysjung/uzys-agent-harness/
|
|
6
|
+
[](https://github.com/uzysjung/uzys-agent-harness/tags)
|
|
7
7
|
[](https://github.com/uzysjung/uzys-agent-harness/actions)
|
|
8
8
|
|
|
9
9
|
|
|
@@ -14,99 +14,119 @@ Install vetted AI-coding skills, plugins, rules, and hooks for Claude Code, Code
|
|
|
14
14
|
|
|
15
15
|
## Install
|
|
16
16
|
|
|
17
|
+
You need Node 20 or newer. If you plan to use Claude Code plugins, the `claude` command must be on your PATH; otherwise plugin assets are skipped with a warning.
|
|
18
|
+
|
|
17
19
|
```bash
|
|
18
20
|
npx -y @uzysjung/agent-harness
|
|
19
21
|
```
|
|
20
22
|
|
|
21
|
-
The wizard walks through six steps:
|
|
23
|
+
The wizard walks you through six steps:
|
|
22
24
|
|
|
23
25
|
```
|
|
24
|
-
1/6 Tracks pick
|
|
25
|
-
2/6 CLI claude / codex / opencode / antigravity
|
|
26
|
-
3/6 Install items
|
|
26
|
+
1/6 Tracks pick what you are building
|
|
27
|
+
2/6 CLI claude / codex / opencode / antigravity — one or more
|
|
28
|
+
3/6 Install items everything is pre-checked for your track; uncheck what you don't want
|
|
27
29
|
4/6 Scope Project (default) or Global
|
|
28
|
-
5/6 Confirm
|
|
30
|
+
5/6 Confirm summary, plus how much context your selection adds to each session
|
|
29
31
|
6/6 Installing
|
|
30
32
|
```
|
|
31
33
|
|
|
32
|
-
Then
|
|
34
|
+
Then open your CLI in the project — the rules and skills are live, and on Claude Code the hooks too:
|
|
33
35
|
|
|
34
36
|
```bash
|
|
35
37
|
claude # or codex / opencode / agy
|
|
36
38
|
```
|
|
37
39
|
|
|
38
|
-
**
|
|
40
|
+
**Your first session.** The install leaves a `CLAUDE.md` (or `AGENTS.md`) with fill-in sections about *your* project. Ask your agent to run the `audit-harness-fit` skill once. It reads the repository and fills those sections from evidence, and you run it again later to check whether the harness still fits the project. There is no "interview me about my stack" step — you already chose the stack at step 1, and the audit fills the rest from the code.
|
|
39
41
|
|
|
40
|
-
|
|
42
|
+
The wizard needs a terminal. For CI, containers, or onboarding scripts, use the flag form: `install --track <name>` is the only required flag — see [non-interactive install](docs/USAGE.md#non-interactive-install).
|
|
41
43
|
|
|
42
|
-
|
|
44
|
+
### Two ways to install
|
|
43
45
|
|
|
44
|
-
|
|
46
|
+
| You want… | Do this |
|
|
47
|
+
|---|---|
|
|
48
|
+
| The harness — rules, hooks, agents, and the skills your stack calls for, curated by track | The wizard above |
|
|
49
|
+
| One skill, nothing else — no harness, no track | `npx skills add uzysjung/uzys-agent-harness --skill <id> -a claude-code` |
|
|
45
50
|
|
|
46
|
-
|
|
47
|
-
npx -y @uzysjung/agent-harness list # what this project got
|
|
48
|
-
npx -y @uzysjung/agent-harness update # refresh it to the current release
|
|
49
|
-
npx -y @uzysjung/agent-harness uninstall # pick what to remove
|
|
50
|
-
```
|
|
51
|
+
Every skill this repo ships is installable on its own with the [skills CLI](https://github.com/vercel-labs/skills); `npx skills add uzysjung/uzys-agent-harness --list` shows the ids. You get the same files the installer copies, `references/` included. Re-run the command to refresh ([details](docs/USAGE.md#one-skill-without-the-harness)). They are listed on [skills.sh/uzysjung/uzys-agent-harness](https://skills.sh/uzysjung/uzys-agent-harness) as well.
|
|
51
52
|
|
|
52
|
-
|
|
53
|
+
## Philosophy — keep only the frame the model needs
|
|
53
54
|
|
|
54
|
-
|
|
55
|
+
Piling rules and skills onto an AI coding tool does not make it better. Every instruction that is always loaded costs context in every session, and telling a frontier model how to do something it already does well only slows it down. This harness starts from the opposite end: **keep a principle only where the model is likely to slip, and take it back out as models improve.**
|
|
55
56
|
|
|
56
|
-
|
|
57
|
+
- **"Don't do X" and "always do Y" degrade today's models.** A pile of prohibitions and mandates removes the model's room to judge. The moment a situation differs slightly from the rule, the model gets stuck or works around it. Once guards start guarding other guards, development slows down while quality stays flat. So the harness writes guidance as *what must be true* — the outcome, the invariant, the boundary — and leaves *how* to the model. Prohibitions are kept for irreversible damage — secrets and shared history — and even those are enforced by a mechanism rather than a sentence: a hook blocks edits to `.env` and key files, and a GitHub ruleset the harness helps you apply protects the default branch. This direction came from measurement, not taste: of the 44 sentences in our own rules, the number observed to change an agent's behaviour was zero. What actually caught incidents was gates, tests, and an independent reviewer.
|
|
57
58
|
|
|
58
|
-
|
|
59
|
+
- **Skills improve as models improve.** Each asset is kept only when there is an observation behind it: "without this, the agent is measurably slower or wrong." Guidance without that evidence is removed from the always-loaded set — it becomes a skill that loads only when needed, or it is retired. So `update` brings you the current judgement — what was added, and what was cut — not just more.
|
|
59
60
|
|
|
60
|
-
|
|
61
|
+
- **`audit-harness-fit` keeps checking.** Run once after install and it fills your project context from the repository. Run later and it finds needless questions, repeated checks, decisions that contradict each other, and procedures that a better model no longer needs — then proposes the edit. Whether the harness fits your project is a question you keep asking, not one you settle at install time.
|
|
61
62
|
|
|
62
|
-
- **
|
|
63
|
+
- **Speed and quality are not a trade-off.** Irreversible damage is blocked by a hook, repeated mistakes are caught by a short rule, and everything else is left to the model. Verification is not "everything, every time": it runs when a user-facing scene is complete, by a separate agent that did not write the code and actually executes it. The goal is the lightest protection that reliably keeps what matters, not more guards.
|
|
63
64
|
|
|
64
|
-
- **
|
|
65
|
+
- **Think and explain from the customer's side of the service you are building.** The agent describes a problem, a change, or a choice first as what the user does and sees, not as file names and functions (`user-centered-explanation`). When a decision needs your approval, it arrives as context → problem → options → recommendation, so you can decide without re-reading the conversation.
|
|
65
66
|
|
|
66
|
-
|
|
67
|
+
Those five are the direction, and the first question for any asset — in or out — is *does this help a person build better with an AI coding tool?* The long form is [docs/NORTH_STAR.md](docs/NORTH_STAR.md).
|
|
67
68
|
|
|
68
|
-
##
|
|
69
|
+
## What you get
|
|
69
70
|
|
|
70
|
-
|
|
71
|
+
- **Rules** — six short files on git policy, change management, documentation, testing, shipping, and CLI development. Dev tracks get five; `tooling` and `full` add the sixth; business tracks get the three that apply to any project.
|
|
72
|
+
- **Hooks** — two, on Claude Code: one loads your spec and change log at session start, one blocks edits to `.env`, lock files, and certificates. That second hook is the only thing in the harness that says "no", and it writes one line to a log every time it does. Codex gets the session-start hook only; its hook API cannot intercept file edits.
|
|
73
|
+
- **Skills** — the harness's own method skills, written and maintained in this repo, plus the stack skills your track calls for. Four go to every track (`north-star`, `objective-brief`, `gh-issue-workflow`, `audit-harness-fit`); dev tracks add five method skills and an incident runbook; stack tracks add `find-skills`, `frontend-design`, and whatever your stack needs (React, shadcn, Supabase, Postgres on `csr-supabase`, for example). Thirteen of the bundled skills can be named directly with `--with` / `--without`.
|
|
74
|
+
- **Agents** — an independent `reviewer` on every track; `implementer` on dev tracks; `data-analyst` and `strategist` only on the tracks that use them.
|
|
75
|
+
- **A working-principles anchor** — one file your CLI reads every session. Your own `CLAUDE.md` stays yours; the harness adds one import line and never touches the rest. Which file is whose: [docs/CONTEXT-FILES.md](docs/CONTEXT-FILES.md).
|
|
71
76
|
|
|
72
|
-
|
|
77
|
+
What reaches which CLI:
|
|
73
78
|
|
|
74
|
-
|
|
79
|
+
| CLI | Rules | Skills | Hooks | Plugins |
|
|
80
|
+
|---|---|---|---|---|
|
|
81
|
+
| Claude Code | ✓ | ✓ | ✓ | ✓ |
|
|
82
|
+
| Codex | ✓ (in `AGENTS.md`) | ✓ | session start only | — |
|
|
83
|
+
| OpenCode | ✓ (in `AGENTS.md`) | ✓ | — | — |
|
|
84
|
+
| Antigravity | ✓ | ✓ | — | — |
|
|
75
85
|
|
|
76
|
-
|
|
86
|
+
Plugins are Claude Code's own mechanism, so they are Claude-only; skills and rules render for all four from the same source, so they stay consistent across tools.
|
|
77
87
|
|
|
78
88
|
## Tracks
|
|
79
89
|
|
|
80
|
-
|
|
90
|
+
Twelve tracks, grouped by what you are building:
|
|
81
91
|
|
|
82
|
-
- **No stack yet** — `base
|
|
92
|
+
- **No stack yet** — `base`: principles, method skills, and testing rules; nothing stack-specific
|
|
83
93
|
- **Frontend + backend** — `csr-supabase` · `csr-fastify` · `csr-fastapi` · `ssr-nextjs` · `ssr-htmx`
|
|
84
94
|
- **Data** — `data`
|
|
85
95
|
- **Business** — `executive` · `project-management` · `growth-marketing`
|
|
86
|
-
- **Meta** — `tooling
|
|
96
|
+
- **Meta** — `tooling`: Bash and Markdown projects with no app stack
|
|
87
97
|
- **Everything** — `full`
|
|
88
98
|
|
|
89
|
-
|
|
99
|
+
A track is a starting point, not a lock-in: everything it pre-checks can be unchecked at step 3, and you can pick more than one. [What each track installs →](docs/TRACKS.md)
|
|
90
100
|
|
|
91
|
-
##
|
|
101
|
+
## Day to day
|
|
92
102
|
|
|
93
|
-
|
|
103
|
+
```bash
|
|
104
|
+
npx -y @uzysjung/agent-harness list # what this project got
|
|
105
|
+
npx -y @uzysjung/agent-harness update # bring it to the current release
|
|
106
|
+
npx -y @uzysjung/agent-harness uninstall # pick what to remove, or remove everything
|
|
107
|
+
```
|
|
94
108
|
|
|
95
|
-
|
|
109
|
+
`update` refreshes the files the harness installed, adds skills a newer release introduced, and tells you when something (a new hook) needs a reinstall instead. It never installs a CLI you did not choose. `update --only skills` limits it to one group. `uninstall` asks item by item in a terminal; `--dry-run` shows the plan first.
|
|
96
110
|
|
|
97
|
-
|
|
111
|
+
**Safe on an existing project.** Before replacing a file you edited, the harness writes a timestamped backup next to it and prints the path. Nothing you wrote or edited is deleted without a backup beside it. Your existing `.mcp.json` servers are merged, not replaced. Details: [installing into an existing project](docs/USAGE.md#installing-into-an-existing-project).
|
|
98
112
|
|
|
99
|
-
|
|
113
|
+
**Project scope is the default.** Nothing goes to `~/.codex/`, `~/.opencode/`, `~/.gemini/`, or global npm unless you choose Global at step 4. Claude Code plugins are the one exception: the `claude` CLI keeps its plugin cache under `~/.claude/plugins/` in either scope and isolates projects by metadata. Besides `.claude/`, install writes `.mcp.json`, a few `.gitignore` lines (when that file exists), an `.env.example` on Supabase tracks, and its own record at `.uzys-agent-harness/` — the full list is in [what the harness writes](docs/USAGE.md#what-the-harness-writes).
|
|
100
114
|
|
|
101
|
-
|
|
115
|
+
## Vetting
|
|
102
116
|
|
|
103
|
-
|
|
117
|
+
An external asset is **vetted** when it has at least 1,000 GitHub stars, is not archived, and its install command has been run and checked in an isolated environment. Two monthly CI jobs re-check the stars and the install path. Vetting is **not** a line-by-line security audit and does not scan asset contents for prompt injection. npm and npx assets are pinned to a version; plugin and skill assets resolve to upstream HEAD.
|
|
104
118
|
|
|
105
|
-
|
|
119
|
+
At step 3, `★ official` marks Anthropic-official marketplaces and this harness's own assets, `⚠ experimental` marks assets under 1,000 stars — never pre-checked, added only by you. Vetted assets carry no badge. Tiers inform; they never block. Treat installed assets like any other third-party dependency: [SECURITY.md](SECURITY.md).
|
|
106
120
|
|
|
107
|
-
|
|
121
|
+
## Docs
|
|
108
122
|
|
|
109
|
-
|
|
123
|
+
- [Usage guide](docs/USAGE.md) — install flags, scope, update, uninstall, per-CLI details, what gets written where
|
|
124
|
+
- [Tracks](docs/TRACKS.md) — what each track pre-checks
|
|
125
|
+
- [Compatibility matrix](docs/COMPATIBILITY.md) — every asset, its install method, which CLIs it reaches, and how it was verified
|
|
126
|
+
- [Which file is whose](docs/CONTEXT-FILES.md) — `CLAUDE.md`, the anchor, `AGENTS.md`, and the other context files
|
|
127
|
+
- [Workflow guide](docs/WORKFLOWS.md) — the opt-in workflow bundles compared, and when you don't need one
|
|
128
|
+
- [Security](SECURITY.md) — what vetting covers, what it doesn't, how to report
|
|
129
|
+
- [North Star](docs/NORTH_STAR.md) · [decisions](docs/decisions/) — why the harness is shaped this way
|
|
110
130
|
|
|
111
131
|
## License
|
|
112
132
|
|
|
@@ -626,7 +626,10 @@ var EXTERNAL_ASSETS = [
|
|
|
626
626
|
// v26.78.0 — Understanding 으로 재분류: 웹 지각(screenshot·DOM). 영상/코드 지각과 같은 축.
|
|
627
627
|
category: "understanding",
|
|
628
628
|
source: "vercel-labs",
|
|
629
|
-
|
|
629
|
+
// #489 (사용자 결정 2026-09-20 a) — 기본 체크에서 opt-in 으로. computer-use 가 같은 일을 하고,
|
|
630
|
+
// 셋 중 설치 비용이 가장 크다(npm devDep → 안 쓰는 프로젝트에 node_modules 만 남는다).
|
|
631
|
+
// 3단계에는 그대로 뜨되 체크 해제, `--with agent-browser` 로 켠다. 기존 설치본은 영향 없음.
|
|
632
|
+
condition: { kind: "opt-in" },
|
|
630
633
|
method: { kind: "npm", pkg: "agent-browser", version: "0.31.0" }
|
|
631
634
|
},
|
|
632
635
|
// v26.78.0 — Understanding 신규 3종 (plugin, opt-in). 에이전트 인지 증강: 영상·코드 지각 + 메모리.
|
|
@@ -2186,4 +2189,4 @@ export {
|
|
|
2186
2189
|
CATEGORIES,
|
|
2187
2190
|
CATEGORY_TITLES
|
|
2188
2191
|
};
|
|
2189
|
-
//# sourceMappingURL=chunk-
|
|
2192
|
+
//# sourceMappingURL=chunk-HHCNPPGS.js.map
|