Presets & TUI 설치

Preset은 rule refs + skill refs의 curated 번들입니다.
TUI로 선택하면 한 번에 전체를 프로젝트에 설치합니다.

Preset YAML 형식

Preset은 presets/<id>.yaml 파일입니다. Rule과 skill의 경로를 나열한 번들입니다.

# presets/fe-agent-harness.yaml
name: FE Agent Harness
description: Complete rule and skill set for GS Retail
  frontend projects built with Next.js / TypeScript.

rules:
  - tech-stack/fe-stack-and-commands      # Next.js, pnpm, TanStack Query
  - architecture/feature-boundaries       # Feature-Sliced Design
  - workflow/plan-first                   # 계획 먼저
  - workflow/fe-tdd                       # TDD
  - workflow/cleanup-after-green          # 테스트 통과 후 정리
  - nextjs-boundaries-hydration/serializable-boundary-props
  - nextjs-boundaries-hydration/hydration-mismatches
  - type-modeling/no-any
  - type-modeling/domain-types
  # ...24개 합계

skills:
  - monorepo/nx-best-practices            # Nx 모노레포 가이드
  - design-system/gsr-design-tokens       # GSR 디자인 토큰
  - design-system/gsr-shared-ui           # 공유 UI 컴포넌트 카탈로그
  - auth/azure-ad-sso-nextjs              # Azure AD SSO (FE)
  - code-review/are-we-done               # PR 전 독립 리뷰
  # ...26개 합계

FE vs BE 하네스 비교

항목	fe-agent-harness	be-agent-harness
주요 언어	TypeScript	Python
프레임워크	Next.js (App Router)	Flask + Connexion
패키지 매니저	pnpm	uv
API 계약	sync-api-contracts-init 스킬	openapi-first-flask-init 스킬
테스트	Vitest/Jest + Playwright	pytest + moto
데이터 레이어	TanStack Query + Zustand	DynamoDB repository seam
Rules 수	24개	21개
Skills 수	26개	19개
공통 항목	plan-first, no-hardcoded-secrets, autonomous-retry, conventional-commits, language-policy, are-we-done, bitbucket-server, pre-stage-secret-scan, generate-pr-summary, address-pr-feedback, audit-security-baseline

TUI 설치 흐름

설치 & 실행 agent-harness-tui

Browse / Presets 탭 선택

장바구니 추가 Space로 선택

Install i 키 누름

완료 .agents/ 생성됨

# 저장소 클론 후 실행
pip install -e .   # 또는 uv sync
agent-harness-tui  # TUI 시작

# 키보드 조작
# Tab       탭 이동 (Browse / Presets / Cart / Installed)
# Space     선택/해제
# i         설치 시작
# q / Esc   종료

ℹ️ Browse탭: rule/skill을 개별 선택. Presets탭: 미리 구성된 번들 선택 (FE 하네스, BE 하네스 등). 둘을 섞어도 됩니다.

설치 결과물

fe-agent-harness 설치 후 프로젝트 파일 구조

📁

{project}/.agents/rules/

설치된 모든 rule .md 파일. 카테고리 폴더 구조 그대로 복사됨.

📁

{project}/.agents/skills/

설치된 모든 skill 폴더. SKILL.md + 부속 파일 포함.

📄

{project}/.agents/manifest.json

설치된 항목 목록 (kind, category, id, name, source_hash). 재설치 시 idempotency 판단에 사용.

📄

{project}/CLAUDE.md

managed block이 삽입/업데이트됨. Claude Code가 읽는 핵심 파일.

CLAUDE.md Managed Block

설치 후 CLAUDE.md에 다음 형식의 블록이 자동으로 삽입됩니다. 절대 손으로 편집하지 마세요 — 다음 설치 시 덮어씁니다.

CLAUDE.md 내 managed block

<!-- AGENT-HARNESS_START -->
## Agent rules & skills (managed by agent-harness — do not edit by hand)

### Rules
- **FE stack & commands** (`.agents/rules/tech-stack/fe-stack-and-commands.md`)
  — Baseline tech stack, package manager, standard commands...
- **Feature-Sliced Design boundaries** (`.agents/rules/architecture/feature-boundaries.md`)
  — Group code by feature; import across features only through each feature's...
...

### Skills
- **nx-best-practices** (`.agents/skills/monorepo/nx-best-practices/SKILL.md`)
  — How to use an Nx monorepo well...
- **are-we-done** (`.agents/skills/code-review/are-we-done/SKILL.md`)
  — Answers "are we done?" before a PR exists...
...
<!-- AGENT-HARNESS_END -->

멱등성 (Idempotency)

같은 항목을 여러 번 설치해도 안전합니다.

상황	동작
처음 설치	파일 복사 + manifest에 추가 + managed block 삽입
이미 설치된 항목 재설치	skipped — 기존 파일 변경 없음, 메타데이터만 업데이트
업데이트된 버전 설치	source_hash 비교 후 변경된 경우만 덮어씀
managed block 재생성	기존 block 완전 교체 (START~END 사이 내용 업데이트)

✅ 실전 팁: 스토어에서 rule/skill 내용이 업데이트됐을 때 재설치하면 자동으로 최신 버전으로 교체됩니다. 팀 전체에 업데이트를 배포할 때 각자 agent-harness-tui를 다시 실행하면 됩니다.

TUI vs 마켓플레이스 — 언제 무엇을 쓰는가

🖥️ TUI 인스톨러

개별 개발자가 로컬 프로젝트에 설치
부분 선택 가능 (preset 일부만)
대화형 브라우징
Python/pip 필요

🛒 Claude Code 마켓플레이스

/plugin install 클릭 한 번
Preset 단위로 설치 (all-or-nothing)
CI/CD 친화적 (스크립팅 가능)
별도 Python 불필요

일상적인 개발에는 TUI, 새 프로젝트 부트스트랩이나 팀 전체 배포에는 마켓플레이스를 권장합니다. 자세한 내용은 Module 04 — Claude Code 플러그인.