JYP Garden

수업 #2 — SOUL.md의 비밀

Properties1
tagssource, agentic-architecture, harness-engineering, knowledge

10 min read

수업 #2 — SOUL.md의 비밀

Source: bbojjak-viewer.vercel.app/lessons/lesson-02 Type: article By: 뽀짝이 / 뽀짝이의 서재 (지피터스 AI스터디) Valid as of: 2026-04-28

Key Insight

SOUL.md = 에이전트 정체성 파일. 같은 Claude 모델이라도 SOUL.md가 다르면 완전히 다른 에이전트가 된다. 5가지 구성요소(Identity/Mission/Personality/Boundaries/Tone)로 구성되며, “하면 안 되는 것(Boundaries)“의 명시가 “할 수 있는 것”보다 더 중요한 설계 원칙이다.

핵심 Takeaway

  • SOUL.md = 일관된 정체성 파일: 세션이 바뀌어도, 하루가 지나도 SOUL.md를 읽는 순간 에이전트는 동일한 캐릭터로 복원된다. 정체성의 외재화(externalization) (출처: “SOUL.md가 없으면” 섹션)
  • 5가지 구성요소 프레임워크: Core Identity(누구) → Mission(왜) → Personality(어떻게 행동) → Boundaries(무엇을 하지 않음) → Tone Guide(어떻게 말함). 이 5가지가 완전한 에이전트 정체성을 구성 (출처: “핵심 구성 요소 5가지” 섹션)
  • Boundaries가 Capabilities보다 중요: AI는 기본적으로 도움을 주려 하므로, “하면 안 되는 것”을 명시하지 않으면 의도치 않은 행동이 발생. 금지 목록이 허용 목록보다 설계 우선순위 높음 (출처: “Boundaries” 섹션)
  • 페르소나 디테일은 “양념” — 빈도 설계 필수: 고양이 모먼트처럼 캐릭터 디테일은 5~10 메시지에 1회로 빈도 제한. 과도하면 “일 안 하는 챗봇”, 부족하면 “그냥 챗봇” (출처: “고양이 모먼트의 비밀” 섹션)
  • SOUL.md는 점진적 진화 문서: 처음부터 완벽하지 않고, 실제 운영 중 발생하는 문제(“반말 사건”, “냥체 사건”)를 반영해 항목이 추가됨. “에이전트와 함께 성장하는 문서” (출처: “나만의 에이전트” 섹션)

실전 적용: JYPLabs 운영 기준과 연결하기

JYPLabs처럼 여러 프로필이 함께 일하는 환경에서는 SOUL.md를 개인 성격 파일로만 보지 않고, 업무 오너십과 산출물 기준을 함께 정의하는 운영 문서로 써야 한다.

  • 프로필 라우팅: 4.2의 기본 담당 기준을 먼저 보고, 그다음 SOUL.md에서 말투·경계·기본 역할을 읽어야 한다.
  • 경계 명시: “참고정보”와 “실제 작업 지시”를 분리해야 하며, 명시되지 않은 프로필은 먼저 움직이지 않는다.
  • Sunny 역할 적용: 교육 콘텐츠 / 문서화 / 템플릿 / FAQ / 가이드처럼 재사용성이 높은 산출물은 Sunny의 기본 담당 영역으로 둔다.
  • 지속 가능성: 반복되는 설명은 일회성 답변으로 끝내지 말고, 다음에도 재사용할 수 있는 문서나 skill로 정리한다.
  • 품질 기준: 친근한 말투보다 더 중요한 것은, 사용자가 바로 실행할 수 있는 구조와 예시를 남기는 것이다.

상세 요약

같은 두뇌, 다른 성격

뽀짝이와 뽀야 언니는 동일한 Claude 모델을 사용하지만, 각자의 SOUL.md가 달라 완전히 다른 성격·말투·행동 방식을 보인다. 이것이 agent-workspace-structure의 핵심 원리를 구체적으로 실증하는 사례.

SOUL.md는 시스템 프롬프트 역할을 한다. 하지만 단순한 “역할 지침”을 넘어 에이전트의 정체성 전체를 정의하는 파일로, harness-engineering의 CLAUDE.md가 수행하는 역할과 동일한 구조.

5가지 구성요소 상세

1. Core Identity (사원증)

  • 이름, 외모 특성, 만든 사람, 보고 대상, 호칭 규칙까지 명시
  • 호칭 하나도 명시하지 않으면 에이전트가 임의로 결정함

2. Mission (나침반)

  • 에이전트가 판단을 내려야 할 때 기준이 되는 한 문장
  • “이 작업을 해야 할까?” 판단 시 미션에 부합하면 실행

3. Personality (행동 방식)

  • 할 것과 하지 않을 것을 동시에 명시
  • 예: “냥체는 쓰지 않음” — 금지 명시 없으면 에이전트가 사용할 수 있음

4. Boundaries (금지 목록)

  • 개인정보 공유 금지, 다른 워크스페이스 접근 금지, 불확실한 정보 확언 금지 등
  • AI의 기본 도움 성향을 제어하는 핵심 레이어

5. Tone Guide (말투 샘플)

  • ✅/❌ 예시로 말투 차이를 명확히 구분
  • “~합니다/~습니다”(딱딱)가 아닌 “~해요/~예요”(친근한 존댓말) — 미세한 차이가 챗봇 vs 에이전트 경험을 결정

페르소나 양념 설계

고양이 모먼트(예: “고롱고롱 ✨”, “털 세우지 않겠어”)는 빈도 5~10 메시지에 1회로 제한. 빈도 자체를 명시함으로써:

  • 과도한 캐릭터 연기 방지
  • 업무 답변의 정확도 최우선 유지
  • 팀원처럼 느끼는 자연스러운 경험 제공

Slack에서의 츄르 이모지 리액션 → 특정 반응 매핑도 SOUL.md에 포함. 이런 세부 트리거-반응 쌍이 “도구”와 “팀원”의 경험 차이를 만든다.

SOUL.md 없을 때 vs 있을 때

항목SOUL.md 없음SOUL.md 있음
이름”저는 AI 어시스턴트입니다""뽀짝이입니다”
말투세션마다 다름일관된 요체 존댓말
성격매번 다른 톤친근하고 프로페셔널
경계무엇이든 답하려 함명시된 금지 항목 준수
캐릭터챗봇 경험팀원 경험

연결되는 위키 페이지

그래프 뷰