151 lines
7.2 KiB
Markdown
151 lines
7.2 KiB
Markdown
# 개발 하네스 — 폐쇄루프 운영 지침
|
|
|
|
> 이 저장소에서 AI 코딩 에이전트가 **자율적으로, 그러나 검증 없이는 완료를 선언할 수 없게** 일하도록
|
|
> 짜 놓은 장치들의 설계와 운영법. 사람과 에이전트 모두 이 문서를 읽는 대상이다.
|
|
|
|
## 왜 필요한가
|
|
|
|
에이전트의 가장 흔한 실패는 코드를 못 짜는 게 아니라 **"됐습니다"라고 말해버리는 것**이다.
|
|
테스트가 깨진 채로, 실행해 보지도 않고, 문서는 옛날 상태인 채로 턴이 끝난다.
|
|
|
|
해법은 프롬프트로 더 강하게 부탁하는 게 아니라, **에이전트가 건너뛸 수 없는 결정적 층**을 두는 것이다.
|
|
확률적인 판단(모델)과 결정적인 검사(훅)를 분리한다.
|
|
|
|
## 5계층 구조
|
|
|
|
| 계층 | 역할 | 이 저장소에서 |
|
|
|---|---|---|
|
|
| **① 하네스** | 에이전트가 사는 환경 | Claude Code + `.claude/settings.json` |
|
|
| **② 루프 계약** | "완료"의 정의 | `AGENTS.md` §4 완료 기준 · `CLAUDE.md` |
|
|
| **③ 상태층** | 세션이 끊겨도 남는 상태 | `docs/BACKLOG.md` 체크박스 · `docs/IMPLEMENTATION_AUDIT.md` · SessionStart 브리핑 |
|
|
| **④ 체커** | 에이전트가 못 건너뛰는 검사 | **Stop 훅 → `dotnet test`** |
|
|
| **⑤ 사람 관문** | 되돌릴 수 없는 일 앞의 확인 | 커밋·푸시·배포는 사용자 승인 (`/release` 스킬) |
|
|
|
|
핵심은 ④다. 나머지는 ④가 있어야 의미가 생긴다.
|
|
|
|
## 구성 요소
|
|
|
|
```
|
|
AGENTS.md ← 도구 중립 작업 계약 (Codex/Cursor 등도 읽음)
|
|
CLAUDE.md ← @AGENTS.md 임포트 + Claude Code 전용 지침
|
|
.claude/
|
|
settings.json ← 훅 등록 + 권한 (커밋됨, 팀 공유)
|
|
hooks/
|
|
session-brief.sh ← SessionStart: 저장소 상태를 컨텍스트에 주입 (상태층)
|
|
verify-on-stop.sh ← Stop: 테스트 게이트 (체커)
|
|
rules/ ← 경로별 자동 로드 규칙 (해당 파일을 열 때만 컨텍스트에 들어옴)
|
|
desktop-wpf.md ← VideoDownloader.App/**, Browser/**
|
|
engine-core.md ← Core/**, Server/**
|
|
mobile-maui.md ← Mobile/**, Mobile.Core/**
|
|
tests.md ← Tests/**
|
|
skills/ ← 호출될 때만 로드되는 절차서
|
|
tdd/SKILL.md ← /tdd RED→GREEN→증거
|
|
verify/SKILL.md ← /verify 완료 기준 전수 점검
|
|
release/SKILL.md ← /release 배포
|
|
.verify-stamp ← 마지막 검증 성공 시점 (자동 생성, gitignore)
|
|
```
|
|
|
|
### 왜 이렇게 나눴나
|
|
|
|
- **CLAUDE.md 는 짧게.** 매 세션 컨텍스트를 먹고, 길수록 지켜지지 않는다. 200줄 이내가 권장선이다.
|
|
- **경로별 규칙은 `rules/` 로.** WPF 함정은 WPF 파일을 열 때만 필요하다. 항상 로드하면 낭비다.
|
|
- **절차는 `skills/` 로.** 배포 순서 같은 건 배포할 때만 필요하다. 안 쓰면 토큰을 안 쓴다.
|
|
- **강제는 훅으로.** CLAUDE.md 는 부탁이고 훅은 강제다. "반드시 X 해라"가 지켜지길 원하면 훅에 넣는다.
|
|
|
|
## 훅 동작
|
|
|
|
### SessionStart — 상태 브리핑
|
|
|
|
세션이 시작되면 브랜치·마지막 커밋·변경 파일·검증 상태·미완료 백로그를 컨텍스트에 넣는다.
|
|
에이전트가 `git status` 를 따로 묻지 않고 현재 상황을 알고 시작한다.
|
|
|
|
### Stop — 테스트 게이트
|
|
|
|
턴을 끝내려 할 때:
|
|
|
|
1. `stop_hook_active` 가 `true` 면 즉시 통과 — **무한 루프 방지**.
|
|
(Claude Code 는 Stop 훅이 8회 연속 차단하면 강제로 넘긴다. 가드가 없으면 그 8회를 다 태운다.)
|
|
2. 소스(`.cs`/`.csproj`/`.xaml`/`.axaml`)의 최신 수정시각을 `.claude/.verify-stamp` 와 비교.
|
|
같으면 즉시 통과 — 대화만 한 턴은 지연 0.
|
|
3. 바뀌었으면 `dotnet test VideoDownloader.Tests` 실행 (증분 약 13초).
|
|
4. 통과 → 스탬프 갱신 후 종료 허용. 실패 → **exit 2 로 종료 차단**, 실패 출력 60줄을 에이전트에게 전달.
|
|
|
|
즉 **테스트를 깨둔 채로 턴을 끝낼 수 없다.**
|
|
|
|
## 사용법
|
|
|
|
### 에이전트 (자율 동작)
|
|
|
|
특별히 할 일이 없다. 세션을 열면 브리핑이 들어오고, 계약(`AGENTS.md`)이 로드되고,
|
|
파일을 열면 해당 영역 규칙이 붙고, 턴을 끝내면 테스트가 돈다.
|
|
|
|
기억할 것 세 가지:
|
|
|
|
1. 기능 작업은 `/tdd` 로 시작한다. 절차를 기억으로 재구성하지 않는다.
|
|
2. 마무리 전에 `/verify` 로 완료 기준을 전수 점검한다.
|
|
3. **Stop 훅이 막으면 우회하지 않는다.** 테스트를 지우거나 Skip 처리하는 것은 회귀를 숨기는 것이다.
|
|
못 고치면 못 고친다고 보고한다.
|
|
|
|
### 사람
|
|
|
|
```powershell
|
|
/hooks # 등록된 훅 확인
|
|
/context # 어떤 지침 파일이 실제 로드됐는지 확인
|
|
/memory # CLAUDE.md 등 열어서 편집
|
|
```
|
|
|
|
**게이트를 잠깐 끄고 싶을 때** — 실험 중이라 테스트가 깨진 게 정상인 상황:
|
|
|
|
```jsonc
|
|
// .claude/settings.local.json (gitignore 대상, 개인용)
|
|
{ "disableAllHooks": true }
|
|
```
|
|
|
|
작업이 끝나면 지운다. 켜 두는 게 기본이다.
|
|
|
|
**게이트가 느리다고 느껴지면** — 변경이 없으면 이미 스킵된다. 그래도 무거우면
|
|
`verify-on-stop.sh` 의 `dotnet test` 를 `--filter` 로 좁히는 대신, 전체 실행 유지를 권한다.
|
|
부분 검증은 회귀를 놓친다.
|
|
|
|
## 확장
|
|
|
|
### 새 경로 규칙 추가
|
|
|
|
`.claude/rules/<이름>.md` 에 프론트매터로 경로를 지정한다.
|
|
|
|
```markdown
|
|
---
|
|
paths:
|
|
- "VideoDownloader.Avalonia/**"
|
|
---
|
|
# Avalonia 영역 규칙
|
|
...
|
|
```
|
|
|
|
해당 경로 파일을 열 때만 컨텍스트에 들어온다. 30줄 안쪽으로 유지한다.
|
|
|
|
### 새 절차 스킬 추가
|
|
|
|
`.claude/skills/<이름>/SKILL.md`. `description` 이 트리거를 결정하므로
|
|
**언제 쓰는지**를 구체적으로 쓴다 — "코드 리뷰용"보다 "PR 올리기 전 변경 diff 를 검토할 때".
|
|
|
|
### 새 게이트 추가
|
|
|
|
무거운 검사(전체 빌드, 통합 테스트)는 `Stop` 에 붙인다. `PostToolUse` 에는 붙이지 않는다 —
|
|
편집할 때마다 돌면 개발이 멈춘다. .NET 빌드는 특히 비싸다.
|
|
|
|
## 원칙
|
|
|
|
- **부탁은 CLAUDE.md, 강제는 훅.** 반드시 일어나야 하는 일을 프롬프트에 적어두고 기대하지 않는다.
|
|
- **게이트는 우회 대상이 아니라 계약이다.** 막히면 원인을 고친다.
|
|
- **완료 보고에는 실제 출력의 숫자를 인용한다.** 기억으로 쓴 "테스트 통과"는 근거가 아니다.
|
|
- **되돌릴 수 없는 일 앞에는 사람을 둔다.** 커밋·푸시·배포는 자동화하지 않는다.
|
|
|
|
## 참고
|
|
|
|
- [Claude Code — 메모리와 CLAUDE.md](https://code.claude.com/docs/en/memory)
|
|
- [Claude Code — 훅 레퍼런스](https://code.claude.com/docs/en/hooks)
|
|
- [Claude Code — 스킬](https://code.claude.com/docs/en/skills)
|
|
- [AGENTS.md 표준](https://agents.md) — 2025년 8월 공개 규격, 2025년 12월 Linux Foundation 산하
|
|
Agentic AI Foundation 으로 이관. Claude Code 는 `AGENTS.md` 를 직접 읽지 않으므로
|
|
`CLAUDE.md` 에서 `@AGENTS.md` 로 임포트하는 것이 공식 권장 방식이다.
|