Agent Harness Store
팀의 AI 운영 노하우를 코드처럼 버전 관리하는 시스템.
Claude Code에게 "우리 팀 방식대로 개발하라"고 알려주는 규칙과 절차의 도서관.
Claude Code에게 "우리 팀 방식대로 개발하라"고 알려주는 규칙과 절차의 도서관.
왜 필요한가
Claude Code는 강력하지만 기본 상태에서는 팀의 컨벤션을 모릅니다. 새 프로젝트를 시작할 때마다 "Flask는 application factory로 만들어", "pnpm을 써", "타입에 any는 쓰지 마"를 매번 다시 설명해야 합니다.
✅ agent-harness-store는 이 지식을 코드로 표현하고, 버전 관리하고, 한 번의 명령으로 어떤 프로젝트에든 설치할 수 있게 합니다.
세 가지 역할
📚 콘텐츠 저장소
rules/, skills/, presets/에 모든 규칙과 절차가 마크다운으로 저장됩니다.
🖥️ TUI 인스톨러
Textual 기반 터미널 앱. 원하는 콘텐츠를 선택하면 프로젝트에 복사하고 CLAUDE.md를 업데이트합니다.
🛒 플러그인 마켓플레이스
/plugin install 한 번으로 preset 전체를 Claude Code에 설치. CI/CD 친화적.
시스템 아키텍처
┌─────────────────────────────────────────────────────────────┐
│ agent-harness-store (콘텐츠 저장소) │
│ │
│ rules/workflow/plan-first.md ← Rule (항상 적용) │
│ rules/type-modeling/no-any.md │
│ skills/monorepo/nx-best-practices/ ← Skill (요청 시 적용) │
│ skills/auth/azure-ad-sso-flask/ │
│ presets/fe-agent-harness.yaml ← Preset (번들) │
└──────────────────┬──────────────────┬──────────────────────┘
│ │
┌────────▼──────┐ ┌───────▼──────────────┐
│ TUI 인스톨러 │ │ Claude Code 플러그인 │
│ (Textual 앱) │ │ 마켓플레이스 │
└────────┬──────┘ └───────┬──────────────┘
│ │
┌────────▼──────────────────▼──────────────┐
│ {project}/.agents/ │
│ rules/workflow/plan-first.md │
│ skills/auth/azure-ad-sso-flask/SKILL.md │
│ manifest.json │
│ CLAUDE.md (managed block 자동 업데이트) │
└────────────────────────────────────────────┘
Rules vs Skills — 핵심 구분
📋 Rules — 항상 적용되는 제약
- Claude가 매 응답마다 자동으로 따름
- "무엇을 하면 안 되는가", "어떤 방식으로 해야 하는가"
- 예:
no-any,plan-first,no-hardcoded-secrets - 24~30개가 항상 컨텍스트에 주입됨
⚡ Skills — 요청 시 실행되는 절차
/skill-name으로 명시적으로 호출- "어떻게 하는가" — 단계별 절차 (how-to)
- 예:
/are-we-done,/pr-review,/generate-unit-tests - 필요할 때만 로드 → 토큰 효율
| 구분 | Rules | Skills |
|---|---|---|
| 적용 시점 | 항상 (자동) | 호출 시만 |
| 파일 위치 | rules/<category>/<id>.md | skills/<category>/<id>/SKILL.md |
| 내용 성격 | 제약/강제 사항 | 단계별 절차 |
| FE 하네스 수량 | 24개 | 26개 |
| BE 하네스 수량 | 21개 | 19개 |
FE & BE 하네스 프리셋
Preset은 rule refs + skill refs의 번들입니다. 설치 한 번으로 프로젝트가 완전한 AI 운영 환경을 갖춥니다.
| 항목 | fe-agent-harness | be-agent-harness |
|---|---|---|
| 프레임워크 | Next.js + TypeScript + Nx | Flask + Python + OpenAPI |
| 패키지 매니저 | pnpm | uv |
| 상태 관리 | TanStack Query + Zustand | — |
| 데이터 레이어 | TanStack Query (서버 상태) | DynamoDB + repository seam |
| 테스트 | Vitest/Jest + Playwright | pytest + moto |
| 코드 품질 | ESLint + TypeScript strict | ruff + mypy |
| Rules 수 | 24개 | 21개 |
| Skills 수 | 26개 | 19개 |
과정 로드맵
00
과정 개요 (현재 페이지)
시스템 전체 그림, Rules vs Skills, 두 가지 배포 채널
01
Rules 이해
Rule 해부 (frontmatter), 카테고리 구조, 5가지 핵심 rule 심층 분석
02
Skills 이해
Skill 해부 (SKILL.md), scaffolder(-init) 패턴, disable-model-invocation
03
Presets & TUI 설치
preset YAML 형식, TUI browse→install 흐름, .agents/ 레이아웃, managed block
04
Claude Code 플러그인
marketplace 구조, /plugin install, build-marketplace 빌드 프로세스
05
내부 아키텍처
Store→models→installer→block→adapter 코드 흐름, 확장 포인트
06
FE 하네스 심층
Next.js/TypeScript 24개 규칙 전체 + 26개 스킬 카탈로그
07
BE 하네스 심층
Flask/Python 21개 규칙 전체 + 19개 스킬 카탈로그
08
QA & 코드리뷰
are-we-done, pr-review, deploy readiness, 14개 QA 스킬 완전 가이드
09
Nx Monorepo
apps/libs 구조, 태그+경계, TS project references, 일상 커맨드
10
Bitbucket Server
REST API 완전 가이드, PR 전체 흐름, Code Insights, 페이지네이션
11
새 콘텐츠 기여
rule/skill/preset 추가, marketplace 재빌드, 기여 체크리스트
R
전체 카탈로그
모든 rules & skills 목록, FE/BE 하네스 구성 비교표
학습 경로 권장
일단 쓰고 싶다 ⚡
00 → 03 (TUI 설치) → 04 (플러그인)
FE 개발자 🖥️
00 → 06 (FE 하네스) → 08 (QA) → 09 (Nx)
BE 개발자 ⚙️
00 → 07 (BE 하네스) → 08 (QA) → 10 (Bitbucket)
시스템 이해 🔍
00 → 01 → 02 → 05 (아키텍처)
기여하고 싶다 🔧
00 → 01 → 02 → 11 (기여)
빠른 레퍼런스 📖
R (카탈로그)
ℹ️ 전제 조건: Claude Code 사용 경험이 있고 Python/Git 기초를 이해한다고 가정합니다. 처음 설치는 Module 03 — Presets & TUI 설치를 먼저 보세요.