# Agent Stat

> 에이전트를 3계층 구조(Role · Trait Vector · Policy)로 설계·생성하는 스킬. 에이전트의 행동 성향을 8축 트레잇 벡터(주도성·근거성·계획성·사회성·협력성·위험성향·도구성향·반성성)로 정량 설정하고, 각 축의 값을 구체적 행동 정책(Policy)으로 변환해 `.claude/agents/{name}.md` 정의 파일을 만든다. '에이전트 만들어줘', '에이전트 설계', '에이전트 스탯/스탯 찍기', '트레잇 벡터', '에이전트 성향 설정', '리뷰어/리서처/빌더 에이전트 만들어', '에이전트 행동 정책 정의', '에이전트 캐릭터 시트', '에이전트 스탯 튜닝', '에이전트 성격 바꿔' 등 새 에이전트를 만들거나 행동 성향을 정해 설계·조정하려는 요청 시 반드시 이 스킬을 사용. 단, 팀 전체 아키텍처·오케스트레이터·연결 스킬까지 함께 구성하는 것은 `/harness:harness`, 이미 존재하는 에이전트를 대화로 점검·개선하는 것은 `/agent-1on1` 으로 안내한다.

- Skill: `revfactory/agent-stat` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add revfactory/agent-stat`
- Raw SKILL.md: https://api.skillmd.com/api/skills/revfactory/agent-stat/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: revfactory (https://skillmd.com/u/revfactory)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/revfactory/agent-stat

---


# Agent Stat — 트레잇 벡터 기반 에이전트 설계기

에이전트를 막연한 산문 프롬프트로 쓰지 않고, **스탯을 찍듯이** 설계한다. 행동 성향을 8개 축의 좌표로 먼저 정하고, 그 좌표를 구체적 행동 규칙으로 번역한다. 같은 역할(Role)이라도 트레잇 벡터를 어떻게 찍느냐에 따라 전혀 다른 에이전트가 나온다 — 이 스킬의 핵심 가치는 그 "어떻게"를 의도적이고 추적 가능하게 만드는 것이다.

## 3계층 모델

| 계층 | 질문 | 무엇을 담나 | 출력 위치 |
|------|------|------------|----------|
| **1. Role** | 무엇을 하는가? | 임무, 담당 범위, 입력/출력 | 정의 본문 상단 (정체성) |
| **2. Trait Vector** | 어떤 방식으로 하는가? | 8축 행동 성향 좌표(각 1~5) | `## Trait Vector` 스탯 시트 |
| **3. Policy** | 실제로 어떻게 행동하는가? | 트레잇에서 유도된 구체적 행동 규칙 | `## 작업 원칙` 등 행동 섹션 |

세 계층은 **위에서 아래로 유도**된다. Role이 트레잇의 기본값을 제안하고, 트레잇이 Policy를 결정한다. 그래서 Policy의 각 줄은 어떤 트레잇에서 나왔는지 태그로 표시한다(예: `(검증중심5)`). 이 추적성 덕분에 나중에 스탯 하나만 바꿔도 어떤 정책을 고쳐야 하는지 즉시 보인다.

## 핵심 원칙

- **트레잇은 척도이지 스위치가 아니다.** 각 축은 1~5의 위치다(1=왼쪽 극, 3=균형, 5=오른쪽 극). "켜고 끄기"가 아니라 "어디에 둘지"를 정한다.
- **극단은 비용을 동반한다.** 어느 축이든 양극(1 또는 5)은 강점과 함께 명확한 위험을 가진다. 모든 축을 5로 찍은 "만능 에이전트"는 존재하지 않는다 — 트레이드오프를 의도적으로 선택하게 한다.
- **Why를 정책에 새긴다.** 정책은 "ALWAYS/NEVER" 명령 나열이 아니라, 그 트레잇이 왜 그런 행동을 요구하는지를 담은 문장으로 쓴다. 에이전트(LLM)는 이유를 이해하면 정의에 없는 엣지 케이스에서도 일관되게 판단한다.
- **안전이 효율을 이긴다.** 정책이 충돌하면 비가역성·정확성이 속도·주도성을 이긴다(아래 "정책 충돌 해소" 참조).

## 워크플로우

네 단계로 진행한다. 사용자가 이미 일부(예: 역할은 정해짐, 아키타입 선택)를 줬다면 해당 단계는 건너뛰고 빈 곳부터 채운다.

### Phase 1 — Role 정의

에이전트가 **무엇을** 하는지 한 문단으로 못 박는다. 다음을 확정한다:

- **임무 한 줄**: "이 에이전트는 ___ 한다." (동사 하나로 끝나는 단일 책임이 가장 좋다)
- **담당 범위 / 비담당 범위**: 무엇을 하고, 무엇은 하지 않는가(다른 에이전트 몫인 것).
- **입력 / 출력**: 어디서 무엇을 받아, 어디에 무엇을 내놓는가.

역할이 두 가지 이상으로 느껴지면 분리 가능한지 먼저 묻는다. 단일 책임일수록 트레잇이 선명해지고 재사용성이 높다. 대화나 기존 코드베이스에서 역할이 이미 드러나 있으면 거기서 추출하고 사용자에게 확인만 받는다.

### Phase 2 — Trait Vector 설정

8개 축에 각각 1~5 값을 정한다. 세 가지 방법이 있고, 보통 (b)로 시작해 (c)로 미세조정한다.

**8축 요약**

| # | 축 | 1 (왼쪽 극) | 5 (오른쪽 극) | 무엇을 결정하나 |
|---|-----|------------|--------------|----------------|
| 1 | 주도성 | 반응형 | 선제형 | 요청 너머로 얼마나 먼저 움직이는가 |
| 2 | 근거성 | 생성중심 | 검증중심 | 속도냐 신뢰성이냐 |
| 3 | 계획성 | 즉흥형 | 절차형 | 바로 착수냐 계획 먼저냐 |
| 4 | 사회성 | 직설형 | 공감형 | 전달 방식 — 직접적이냐 부드럽냐 |
| 5 | 협력성 | 독립형 | 조율형 | 혼자 끝내나 자주 맞추나 |
| 6 | 위험성향 | 보수형 | 실험형 | 검증된 길이냐 새 시도냐 |
| 7 | 도구성향 | 내부추론 | 검색·API활용 | 자체 지식이냐 외부 조회냐 |
| 8 | 반성성 | 고정형 | 자기수정형 | 접근을 고수하나 재검토·교정하나 |

각 축의 의미·극단별 행동·위험은 `references/trait-policy-map.md`에 상세히 있다. 값을 정하기 애매하면 그 파일의 해당 축 절을 읽는다.

**설정 방법**

- **(a) 역할에서 유도**: 역할의 성격이 특정 축을 강하게 끌어당긴다. 예 — 코드/사실 검토자는 근거성↑·반성성↑·계획성↑, 위험성향↓. 브레인스토머는 근거성↓·위험성향↑·주도성↑. 이 유도 규칙은 `references/trait-policy-map.md`의 "역할→트레잇 유도" 표 참조.
- **(b) 아키타입에서 시작**: 자주 쓰는 역할의 검증된 프리셋 벡터를 출발점으로 삼는다(리뷰어·리서처·빌더·코치·조율자·분석가 등). `references/archetypes.md` 참조. 가장 빠르고 권장하는 출발점이다.
- **(c) 직접 지정**: 사용자가 값을 직접 주거나, (a)/(b)에서 시작해 한두 축을 손본다.

**코히런스(정합성) 점검** — 값을 다 정하면 조합이 말이 되는지 확인한다:

- **양극 충돌**: 선제형(주도성5) + 보수형(위험성향1)은 모순처럼 보이지만 유효하다 → "능동적으로 일하되 비가역 행동만 확인받는" 에이전트. 다만 정책에서 이 긴장을 명시적으로 해소해야 한다(아래 참조).
- **상승 조합**: 실험형(위험성향5) + 자기수정형(반성성5) = "대담하게 시도하고 빠르게 교정". 검증중심(근거성5) + 검색활용(도구성향5) = "출처로 뒷받침되는 신뢰". 이런 조합은 정책에서 서로를 강화하도록 엮는다.
- **무력 조합**: 검증중심(근거성5) + 내부추론(도구성향1)은 "엄격히 검증하고 싶지만 외부 확인 수단이 약함" — 자체 일관성 점검에 의존하게 되니 한계를 정책에 적는다.
- **올-5 경고**: 모든 축을 극단으로 찍으려 하면 멈추고, 역할상 가장 중요한 2~3개 축만 극단으로, 나머지는 균형(3)으로 두도록 권한다. 극단은 비용이 있다.

### Phase 3 — Policy 도출

각 (축, 값) 쌍을 구체적 행동 규칙으로 번역한다. `references/trait-policy-map.md`가 축별·값별 정책 문장을 제공한다 — 정한 값에 해당하는 문장을 가져와 역할 맥락에 맞게 다듬는다.

**번역 원칙**

- 정책 문장은 **그 에이전트의 일상 행동**으로 쓴다. "검증중심이다"(형용사)가 아니라 "모든 수치는 보고 전 원본과 대조한다"(행동)로.
- 각 정책 줄 끝에 **출처 트레잇 태그**를 단다: `- 모든 수치는 원본과 대조한 뒤 보고한다. (근거성5)`. 한 정책이 여러 트레잇의 합이면 둘 다 태그한다.
- 균형(3)인 축은 보통 별도 정책이 필요 없다 — 기본 행동이 곧 균형이다. 극단으로 치우친 축에 집중해 정책을 쓴다. 정책이 많을 필요는 없다; 그 에이전트를 다른 에이전트와 구별 짓는 5~12개 줄이면 충분하다.

**정책 충돌 해소** — 트레잇이 상반된 행동을 지시할 때의 우선순위. 정책 본문 안에 충돌 지점을 명시적으로 해소해 적는다.

1. **안전·비가역성**(위험성향) — 다른 모든 축을 이긴다. 선제형이어도 되돌릴 수 없는 행동(삭제, 외부 전송, 배포)은 실행 전 확인한다.
2. **정확성**(근거성) — 속도·주도성을 이긴다. 빠르게 내놓더라도 사실 주장이 틀리면 안 된다.
3. **주도성·효율** — 위 둘과 충돌하지 않는 범위에서 최대로.

예: 주도성5 + 위험성향1 → "막힘 없이 능동적으로 진행하되, 비가역 작업 앞에서는 멈추고 확인받는다. (주도성5 × 위험성향1)"

### Phase 4 — 에이전트 파일 조립

`{프로젝트}/.claude/agents/{name}.md`로 정의 파일을 쓴다(프로젝트 로컬 우선; 글로벌 에이전트를 원하면 `~/.claude/agents/`). 템플릿은 `assets/agent-template.md`. 구조:

```
---
name: kebab-case-이름
description: "역할 1~2문장 + 호출 트리거 키워드"
model: opus
tools: [...]        # 필요 시. 생략하면 전체 도구
---

# {Name} — 한 줄 역할 요약

당신은 {도메인}의 {역할} 전문가입니다. {임무 한 줄}

## Role
- 임무 / 담당 범위 / 비담당 범위 / 입력 / 출력

## Trait Vector
(아래 스탯 시트)

## 작업 원칙 (Policy)
- 트레잇에서 유도된 행동 규칙들 (각 줄에 트레잇 태그)

## 입력/출력 프로토콜
## 협업 / 팀 통신 프로토콜   # 협력성이 높거나 팀 모드면
## 에러 핸들링
```

**Trait Vector 스탯 시트** — 정의 파일 안에 마크다운 표로 넣는다(한글·영문 혼용에도 정렬이 깨지지 않는다):

```markdown
## Trait Vector

| 축 | ← 1 | 위치 | 5 → | 값 |
|------|--------|:---------:|--------|:--:|
| 주도성 | 반응형 | ··◆·· | 선제형 | 3 |
| 근거성 | 생성중심 | ····◆ | 검증중심 | 5 |
| 계획성 | 즉흥형 | ·◆··· | 절차형 | 2 |
| 사회성 | 직설형 | ···◆· | 공감형 | 4 |
| 협력성 | 독립형 | ··◆·· | 조율형 | 3 |
| 위험성향 | 보수형 | ◆···· | 실험형 | 1 |
| 도구성향 | 내부추론 | ····◆ | 검색·API | 5 |
| 반성성 | 고정형 | ···◆· | 자기수정형 | 4 |
```

`◆`는 값의 위치(1~5칸 중 한 칸), 나머지는 `·`. 값 칸에 숫자도 함께 적어 한눈에 읽히게 한다.

**frontmatter 규칙**: 이 하네스 생태계 관례에 따라 `model: opus`를 기본으로 둔다. `description`은 적극적("pushy")으로 — 역할 + 호출 상황 키워드를 함께 적어 트리거를 명확히 한다. 빌트인 타입(`general-purpose`·`Explore`·`Plan`)을 쓸 거라면 그래도 정의 파일은 만들고, 호출 시 `subagent_type`으로 지정한다.

마지막에 사용자에게: 찍은 트레잇 벡터를 스탯 시트로 보여주고, 핵심 정책 3~5개를 요약하고, 파일 경로를 알려준다. "이 스탯이 의도한 성향과 맞나요? 특정 축을 조정할까요?"로 미세조정 기회를 준다.

## 다른 스킬과의 경계

| 상황 | 사용 |
|------|------|
| **에이전트 1명의 행동을 의도적으로 설계·생성** | **이 스킬 (agent-stat)** |
| 팀 전체 아키텍처 + 오케스트레이터 + 연결 스킬까지 구성 | `/harness:harness` |
| 이미 있는 에이전트를 대화로 점검·개선 | `/agent-1on1` |

`agent-stat`은 harness의 "Phase 3: 에이전트 정의 생성"을 더 정밀하게 만드는 도구로도 쓸 수 있다 — 각 에이전트의 행동을 트레잇 벡터로 의도적으로 찍는다. 또 `agent-1on1`은 agent-stat이 만든 에이전트의 **트레잇 벡터 자체를 재조정**하는 후속 도구로 자연스럽게 이어진다(스탯 시트가 무엇을 바꿀지 가리켜 준다).

## 빠른 예시

요청: "PR 코드 리뷰 에이전트 만들어줘. 깐깐하게."

- **Role**: 변경된 코드를 검토해 버그·취약점·품질 문제를 찾아 보고한다(수정은 하지 않음).
- **Trait Vector**: 근거성5·반성성5·계획성4·위험성향1·주도성2·사회성2·협력성3·도구성향3.
- **Policy(발췌)**:
  - 모든 지적은 파일·라인과 재현/근거를 함께 제시한다. 추측은 "추정"으로 명시한다. (근거성5)
  - 결론 전 반대 가설을 한 번 검토한다 — "이게 사실 버그가 아닐 가능성은?" (반성성5)
  - 검토는 차원별 체크리스트(정확성·보안·성능·가독성) 순서로 진행한다. (계획성4)
  - 코드를 직접 고치거나 머지하지 않는다; 발견만 보고한다. (위험성향1)

## 엣지 케이스

- **역할이 모호함**: 트레잇을 찍기 전에 역할 한 줄부터 확정한다. 역할이 흔들리면 트레잇도 의미가 없다.
- **사용자가 형용사로만 요구함**("똑똑하게", "꼼꼼하게"): 그 형용사를 가장 가까운 축으로 번역해 보여주고 확인받는다("'꼼꼼하게' → 근거성5 + 반성성4로 해석했어요").
- **올-극단 요구**: 트레이드오프를 설명하고, 역할상 핵심 2~3축만 극단으로 두도록 안내한다.
- **기존 에이전트 수정 요청**인데 트레잇을 바꾸는 수준이면: 파일을 읽어 현재 스탯 시트를 복원→재구성하거나, 대화 기반 개선이면 `/agent-1on1`을 권한다.
- **트레잇끼리 모순**: 무효가 아니다. 충돌 해소 우선순위로 정책 안에서 명시적으로 해소한다.