JYP Garden

에이전트 워크스페이스 구조 (Agent Workspace Structure)

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

9 min read

에이전트 워크스페이스 구조 (Agent Workspace Structure)

LLM 에이전트의 정체성·규칙·기억·도구·루틴을 .md 파일 집합으로 분리 정의하는 아키텍처 패턴. CLAUDE.md 하네스 엔지니어링의 실증 사례이자 일반화된 에이전트 설계 원칙.

설명

“같은 Claude 모델이어도 워크스페이스가 다르면 완전히 다른 에이전트가 된다.”

이 원칙이 에이전트 워크스페이스 구조의 핵심이다. LLM 자체(두뇌)는 고정되어 있지만, 에이전트를 둘러싼 컨텍스트 파일 집합(워크스페이스)이 행동·역할·기억·도구 접근 권한을 결정한다.

이는 harness-engineering의 CLAUDE.md 패턴과 동일한 원리를 일반 에이전트 프레임워크로 확장한 것이다.

파일 구조 (뽀짝이 사례)

OpenClaw 프레임워크 기반 에이전트 뽀짝이(2026-02 기준) 워크스페이스 구성:

파일역할Claude Code 하네스 대응
SOUL.md성격·말투·행동 방식 — 에이전트 페르소나 정의 (5요소: Identity/Mission/Personality/Boundaries/Tone)System Prompt 역할 지침
USER.md팀원 정보·권한 체계 — 누가 어떤 요청을 할 수 있는지사용자 컨텍스트
AGENTS.md절대 규칙·폴더 구조·파일명·로깅 규칙 — 실제 사고에서 탄생한 구체적 금지 규칙 누적 (9일에 0→14개). “SOUL.md가 DNA라면 AGENTS.md는 사내 업무 매뉴얼”CLAUDE.md 핵심 지침
MEMORY.md장기 기억 요약 — 세션 시작 시 로드영구 메모리 파일
memory/날짜별 상세 작업 일지 (YYYYMMDD.md)작업 로그
TOOLS.md도구 사용법·API 키 위치·접속 계정MCP 연결 정보
HEARTBEAT.md시간별 루틴·트리거 조건Stop Hook + CronCreate
IDENTITY.md이름·Slack Bot ID·아바타 메타데이터에이전트 ID

(출처: bbojjak-openclaw-agentic-architecture-lesson01)

핵심 원칙

1. 파일 = 에이전트 정체성 레이어

모델(LLM)과 정체성(워크스페이스 파일)을 분리하면:

  • 모델 업그레이드 시 파일 변경 없이 성능만 향상
  • 역할 전환 시 모델 교체 없이 파일만 교체
  • 멀티 에이전트 운영 시 같은 모델로 N개의 독립 에이전트 실행

2. 단기 기억(세션) vs 장기 기억(파일) 분리

세션(.jsonl)      → 단기: 한 대화의 맥락 (컨텍스트 윈도우 제한)
MEMORY.md        → 장기: 세션 간 유지할 핵심 정보 요약
memory/ 폴더     → 아카이브: 날짜별 상세 기록 (검색 가능)

세션이 끝나도 지식이 증발하지 않도록 영구 기억 파일에 분리 저장하는 것이 장기 에이전트 운영의 핵심.

3. 워크스페이스 격리 = 에이전트 격리

같은 하드웨어에서 여러 에이전트를 실행할 때, 워크스페이스 디렉토리를 분리하면 세션·기억·도구 접근이 완전히 격리된다. “방을 따로 쓰는 룸메이트” 구조.

멀티에이전트 적용

에이전트워크스페이스역할
bboya/workspace/bboya/개인 비서 (반말, 일정 관리)
bbojjak/workspace/bbojjak/스터디 운영 비서 (존댓말, CS·운영)
dahtmad/workspace/dahtmad/집사 분신 에이전트

세 에이전트 모두 Claude 모델 사용, 하지만 SOUL.md가 달라 완전히 다른 캐릭터.

shared/team/ — 공용 거실

멀티에이전트 운영 시 각 워크스페이스 외에 공용 폴더가 추가된다:

~/.openclaw/
├── workspace-bboya/
├── workspace-bbojjak/
└── shared/team/          ← 공용 거실
    ├── TEAM.md           ← 팀 헌장 (미션·역할 분담·핵심 가치)
    └── COLLAB-RULES.md   ← 협업 규칙 (위임 4요소·보고 체계)
  • 각자의 방(워크스페이스)은 절대 침범 불가
  • shared/team/은 모든 에이전트가 읽기 가능
  • TEAM.md: “우리는 왜 존재하는가” — 매 세션 시작 시 로드
  • COLLAB-RULES.md: “어떻게 일하는가” — 위임·보고 규칙

(출처: bbojjak-openclaw-multi-agent-team-lesson04)

CLAUDE.md 하네스와 대응

harness-engineering의 4단계 구조와 직접 대응:

워크스페이스 파일하네스 단계
SOUL.md + AGENTS.mdPhase 1: CLAUDE.md 지침
TOOLS.mdPhase 4: MCP 연동
HEARTBEAT.mdPhase 3: Stop Hook + CronCreate
MEMORY.md + memory/Phase 2: 영구 메모리 Skill

파일이 세션 사이의 다리

agent-session-architecture에 따르면, 에이전트는 채팅 컨텍스트(Slack 채널, DM 등)마다 독립 세션을 운영한다. 각 세션의 대화 맥락은 서로 분리되지만, 워크스페이스 파일은 모든 세션이 공유한다.

세션 A (Slack #채널1) ──→ AGENTS.md, memory/, SOUL.md (공유)
세션 B (Slack DM)     ──→ AGENTS.md, memory/, SOUL.md (공유)
세션 C (텔레그램)      ──→ AGENTS.md, memory/, SOUL.md (공유)
  • memory/ 파일: 채널 간 공유할 중요 결정을 기록 → 모든 세션에서 참조 가능
  • AGENTS.md: 전 세션에서 시스템 프롬프트로 로드 → 항상 원본 유지 (컴팩션 영향 없음)

이 구조 덕분에 세션이 분리되어 있어도 “조직의 기억”은 유지된다. (출처: bbojjak-openclaw-session-architecture-lesson06)

관련 개념

Hermes Agent 워크스페이스 구조 비교

hermes-agent의 ~/.hermes/ 구조는 OpenClaw의 ~/.openclaw/와 파일 역할이 대응되지만 설계 철학이 다르다. (출처: obsidian-hermes-agent-build-guide)

파일/폴더Hermes (~/.hermes/)OpenClaw (~/.openclaw/workspace-x/)
인격SOUL.mdSOUL.md
업무 규칙(AGENTS.md = 프로젝트 컨텍스트)AGENTS.md (절대 규칙·패턴 누적)
장기 기억memories/MEMORY.md (2,200자)MEMORY.md
사용자 프로필memories/USER.md (1,375자)USER.md
도구 정보(config.yaml)TOOLS.md
루틴(cron via gateway)HEARTBEAT.md
재사용 절차skills/<name>/SKILL.md(스킬 = AGENTS.md에 절차 기술)
세션 기록SQLite FTS5 (자동)memory/YYYYMMDD.md

핵심 차이: Hermes는 skills/ 폴더 + SQLite 세션 검색 + Profiles CLI alias가 차별화 포인트. OpenClaw는 6개 파일 자동 주입 + sessions_send 실시간 에이전트 통신이 강점.

소스

그래프 뷰