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

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

3계층 모델

세 계층은 위에서 아래로 유도된다. 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축 요약

각 축의 의미·극단별 행동·위험은 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 스탯 시트 — 정의 파일 안에 마크다운 표로 넣는다(한글·영문 혼용에도 정렬이 깨지지 않는다):

## 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개를 요약하고, 파일 경로를 알려준다. "이 스탯이 의도한 성향과 맞나요? 특정 축을 조정할까요?"로 미세조정 기회를 준다.

다른 스킬과의 경계

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을 권한다.
• 트레잇끼리 모순: 무효가 아니다. 충돌 해소 우선순위로 정책 안에서 명시적으로 해소한다.