ai-harness

AI Harness — 팀별 AI 에이전트 셋업 시스템

English README

목차

• 설계 철학
• 아키텍처
• 유저 플로우
• 빠른 시작
• 스킬 목록
• 팀 프로필
• Hook 시스템 (Guard)
• 컨벤션 시스템 (Guide)
• Task Workflow 시스템 (Gear)
• OMC 연동
• Init 후 프로젝트 구조
• 설계 문서
• 요구사항

플러그인을 설치하고 /harness-init을 실행하면, 팀에 맞는 AI 작업 환경을 자동으로 구성합니다.

• backend 프로젝트를 분석하여 팀에 맞는 보안 Hook, 코드 컨벤션, 스킬을 자동으로 구성합니다.
• planning 팀은 현재 runtime이 Codex인지 Claude Code인지 감지한 뒤 글로벌 planner bundle을 세팅합니다.

세팅이 끝나면 하네스는 빠지고, Claude Code / Codex 에이전트가 설치된 규칙과 스킬을 사용합니다.

설계 철학

철학	설명
추천 + 선택	베스트 프랙티스를 추천하고, 팀이 선택한다
셋업 후 빠지기	init 시 세팅해주고, 이후엔 Claude Code가 동작. 하네스는 개입하지 않는다
최소 강제, 최대 안내	강제는 보안 Hook 5개뿐. 나머지는 컨벤션과 워크플로우로 안내한다
팀 자율성	각 팀이 자기 도메인, 컨벤션, 스킬을 자유롭게 구성한다

아키텍처

Three-Pillar Architecture

Guard(안전) + Guide(컨벤션) + Gear(AI 최적화) 3축으로 구성됩니다.

축	역할	구성 요소
Guard	보안 — 위험 명령 차단, 시크릿 유출 방지	5개 글로벌 Hook
Guide	컨벤션 — 팀별 코드 스타일, 아키텍처 규칙	CLAUDE.md, convention-*.md, context-map.md
Gear	AI 최적화 — 프로젝트 맞춤 에이전트/스킬/워크플로우	Project-Aware Agents, Domain Skills, Task Workflows

유저 플로우

초기화 (/harness-init)

팀에 따라 다른 경로로 초기화됩니다.

경로	단계
공통 (개발팀)	글로벌 보안 Hook 등록 → 프로젝트 분석
Planning	Runtime 감지 → Planner Bundle 설치 → AGENTS.md/CLAUDE.md 변환 → 26+ Skills 등록
Backend	CLAUDE.md 최적화 → 컨벤션 생성 → 팀 Hook → context-map → 맞춤 에이전트 → Task Workflow → 검증
Frontend	컨벤션 생성 → 팀 Hook 등록

일상 사용

초기화 후 평소처럼 에이전트에서 작업하면 3축이 자동으로 동작합니다.

개발자: "지원자 목록 조회 API 만들어줘"

[Harness] task-workflow 매칭 → implement-feature
    ↓
[Harness] architect 에이전트: 요구사항 분석 + 설계
    ↓
[Guide] developer 에이전트: convention-backend.md 참고하여 코드 생성
    → /api/v1/applicants (버저닝 적용)
    → CommonResponse<T> (공통 응답 포맷)
    ↓
[Guard] Hook이 코드 작성 시 자동 검증
    → SELECT * 사용? → 차단 + "컬럼을 명시하세요"
    → 시크릿 하드코딩? → 차단 + "환경 변수 사용하세요"
    ↓
[Harness] reviewer 에이전트: 컨벤션 + 아키텍처 리뷰 (self-review 방지)

기획자: "jira NMRS-15863 보여줘"
    ↓
planner bundle의 jira skill 사용
    ↓
"create-prd" / "user-stories" / "jira-checklist" 같은 스킬로 후속 작업

관리 (필요할 때)

"backend 팀 추가해줘"    → /harness-team
"왜 차단됐어?"           → /harness-rules
"하네스 상태 보여줘"     → /harness-status

빠른 시작

설치

# 마켓플레이스 등록
claude plugin marketplace add https://github.com/cano721/ai-harness.git

# 플러그인 설치
claude plugin install ai-harness

초기화

개발 팀:

"하네스 초기화해줘"
또는
"이 프로젝트 분석해서 컨벤션 만들고 보안 설정해줘"

기획 팀:

"planning 팀으로 하네스 초기화해줘"
또는
"기획자 모드로 글로벌 planner bundle 설치해줘"

초기화 흐름:

1. 팀 선택 — planning / backend 등 팀 선택
2. planning — 현재 runtime 감지 후 teams/planning/bundle-codex/ 또는 teams/planning/bundle-claude/를 글로벌 위치에 설치
   • 설치 전 inspect로 runtime, 대상 경로, 설치 개수를 먼저 보여줍니다.
   • 설치 중 텍스트 자산은 runtime에 맞게 자동 변환됩니다. 예: AGENTS.md → CLAUDE.md, ~/.codex → ~/.claude
3. backend — 보안 Hook 확인 후 현재 프로젝트 분석 및 로컬 .ai-harness/ 세팅
4. 완료 요약 — 설치된 자산 수, readiness, 다음 추천 명령 표시

상태 확인

"하네스 상태 보여줘"

현재 적용된 팀, Hook, 오늘의 이벤트 요약을 표시합니다.

문제 해결

왜 차단됐는지 알고 싶을 때:

"왜 차단됐어?"

스킬 목록

7개 스킬로 하네스를 완전히 제어합니다. 모두 자연어로 호출 가능합니다.

스킬	사용 예시	기능
harness-init	"하네스 초기화해줘"	planning은 글로벌 planner bundle 설치, backend는 프로젝트 로컬 하네스 세팅
harness-status	"하네스 상태 보여줘"	설정 상태 + 차단 현황 + 진단 + 미결정 사항
harness-rules	"적용된 규칙 보여줘"	현재 보안 규칙 목록, 마지막 차단 사유
harness-team	"backend 팀 추가해줘"	로컬 프로젝트 팀 추가/제거, 컨벤션 수정
harness-exclude	"이 프로젝트 제외해줘"	글로벌 하네스 제외 프로젝트 관리
harness-metrics	"메트릭 분석해줘"	에이전트 작업 효율 메트릭 분석 + 개선 제안
harness-scaffold	"CRUD 만들어줘"	컨벤션 기반 코드 보일러플레이트 생성

팀 프로필

현재 Backend 팀과 Planning 팀(beta) 이 제공됩니다. 다른 팀은 고도화 후 순차 제공 예정입니다.

제공 중

팀	핵심 역할	컨벤션	Hook	스킬
BE	API/DB 개발	패키지 구조, DTO 네이밍, REST 규칙	sql-review, api-compat, entity-review, coverage-check	entity, migration, api-design, convention, agent-map
Planning	PRD, Jira, 유저 스토리, 체크리스트	글로벌 AGENTS/CLAUDE + planner bundle	없음	create-prd, user-stories, jira, jira-checklist 포함 26개 skill + 16개 agent

준비 중 (향후 제공)

팀	핵심 역할	상태
FE	React/Vue 개발	준비 중
QA	테스트/검증	준비 중
DevOps	인프라/배포	준비 중
디자인	디자인 시스템	준비 중

개발 팀은 초기화 후 다음 파일을 받습니다:

• .ai-harness/teams/{team}/skills/convention-{team}.md — 팀별 코드 스타일
• .ai-harness/teams/{team}/CLAUDE.md — 팀별 최소 규칙 + 스킬 참조

planning 팀은 로컬 프로젝트 대신 runtime별 planner bundle을 설치 소스로 사용합니다: