3부·10장 AGENTS.md와 USER.md — 작업 규칙과 사용자 정보
3부·10장 AGENTS.md와 USER.md — 작업 규칙과 사용자 정보
성격 좋은 에이전트는 함께 일하기 즐겁습니다. 그런데 그것만으로는 부족합니다. 말투는 멀쩡한데, 어떤 날은 알아서 잘하다가 어떤 날은 사소한 것까지 묻고, 또 어떤 날은 너무 과감하게 행동하면 곤란하죠. 실무에서 진짜 중요한 건 똑똑함보다 일관성입니다.
OpenClaw에서 그 일관성을 만드는 핵심 장치가 AGENTS.md와 USER.md입니다. SOUL.md가 에이전트의 성격이라면, AGENTS.md는 일하는 규칙이고 USER.md는 누구를 위해 일하는지에 대한 브리프입니다. 이 셋이 분리되어 있어야 에이전트는 매번 기분 따라 움직이는 조수가 아니라, 흔들리지 않는 운영 파트너가 됩니다.123
왜 성격 다음에 규칙과 사용자 정보가 와야 할까
사람을 뽑을 때도 비슷합니다. 성격이 좋다고 바로 일을 맡기지는 않습니다. 어떤 일은 먼저 처리하고, 어떤 일은 보고하고, 누구 스타일에 맞춰 커뮤니케이션해야 하는지 알아야 비로소 믿고 맡길 수 있습니다.
SOUL.md가 에이전트의 목소리를 정한다면, AGENTS.md는 행동의 브레이크와 가속페달을 정합니다. 그리고 USER.md는 그 행동의 방향을 정합니다. 같은 모델이라도 이 세 파일이 분리되어 있으면 이런 차이가 생깁니다.
SOUL.md는 어떻게 말할지를 정합니다.AGENTS.md는 어떻게 일할지를 정합니다.USER.md는 누구 기준으로 판단할지를 정합니다.
이 구분이 흐려지면 문제가 바로 생깁니다. 사용자 정보가 SOUL.md에 섞이면 다른 사람에게 재사용하기 어려워지고, 승인 규칙이 USER.md에 섞이면 운영 정책을 찾기 어려워집니다. 파일을 나누는 이유는 예쁘게 정리하려는 게 아니라, 수정과 테스트를 빠르게 하기 위해서입니다.36
OpenClaw는 이 파일을 매번 컨텍스트로 읽는다
OpenClaw는 워크스페이스 안의 주요 마크다운 파일을 세션 컨텍스트에 주입해 에이전트가 매번 같은 기준으로 시작하도록 만듭니다. 기본적으로 AGENTS.md, SOUL.md, USER.md 같은 파일들이 시작 맥락에 들어가고, 파일이 너무 크면 잘린 상태로 들어갑니다.125
이 말은 곧 두 가지를 뜻합니다. 첫째, 이 파일들은 장식이 아니라 실제 행동에 영향을 주는 운영 문서입니다. 둘째, 길다고 좋은 것이 아닙니다. 너무 길면 잘리고, 너무 많은 정보가 섞이면 정작 중요한 규칙이 흐려집니다. 그래서 좋은 AGENTS.md와 USER.md는 백과사전보다 체크리스트에 가깝습니다.156
실제로 작업하다 보면 왜 갑자기 이 규칙을 안 지키지? 싶은 순간이 옵니다. 그럴 때는 감으로 추측하지 말고 /context list로 어떤 파일이 얼마만큼 주입되고 있는지 확인하는 습관이 유용합니다. 문서가 너무 커서 뒤쪽이 잘린 경우, 원인은 에이전트가 아니라 운영자 쪽에 있는 셈입니다.5
AGENTS.md는 에이전트의 운영 계약서다
AGENTS.md를 한 문장으로 말하면 이렇습니다. 에이전트가 묻지 않고 해도 되는 일과, 반드시 멈추고 물어봐야 하는 일을 가르는 문서입니다.
성격은 좋아도 규칙이 없으면 에이전트는 두 극단으로 흔들립니다. 너무 소심해서 매번 허락을 구하거나, 반대로 너무 자신만만해서 굳이 하면 안 되는 일까지 해버립니다. AGENTS.md는 그 흔들림을 줄입니다.
좋은 AGENTS.md는 보통 네 가지 질문에 답합니다.
세션을 시작하면 무엇부터 확인할까
어디까지 자율적으로 행동할까
어떤 일은 반드시 승인받을까
중요한 상태와 결정을 어디에 남길까
공식 템플릿도 시작 컨텍스트를 우선 활용하고, 이미 주어진 정보를 불필요하게 다시 읽지 말라고 안내합니다. 즉, 부지런함보다 절차가 중요하다는 뜻입니다.4
자율 실행과 승인 게이트를 분리하라
실무에서 가장 효과가 큰 설계는 간단합니다. 그냥 해도 되는 일과 먼저 물어야 하는 일을 분리하는 것입니다.3
예를 들어 아래 같은 일은 자율 실행 영역에 두기 좋습니다.
파일 읽기, 정리, 요약, 초안 작성
비파괴적인 수정과 형식 정리
오류 재현, 로그 확인, 자료 조사
일정 초안, 보고서 초안, 할 일 목록 정리
반대로 아래 일은 승인 게이트가 있어야 합니다.
메시지 발송, 이메일 전송, 게시물 공개
파일 삭제, 데이터 변경, 결제, 배포
돈이 드는 API 호출 확대나 유료 기능 활성화
전략 변경, 우선순위 뒤집기, 대외 커뮤니케이션
핵심 기준은 하나입니다. 이미 정해진 방향 안의 실행인가, 아니면 새로운 방향을 만드는 결정인가. 전자라면 행동하고 보고하면 되고, 후자라면 제안하고 승인받아야 합니다. 이 기준이 선명할수록 에이전트는 덜 귀찮고, 더 안전해집니다.3
보안 규칙은 추상어가 아니라 금지문으로 써야 한다
안전하게 행동해라는 규칙은 멋있지만 별 도움이 안 됩니다. 실제로 행동을 바꾸는 문장은 더 직설적입니다.
예를 들어 이런 문장이 좋습니다.
파괴적 명령은 명시적 승인 없이는 실행하지 않는다.
삭제가 필요하면
rm보다 복구 가능한 방법을 우선한다.비공개 정보, 토큰, 개인 연락처는 외부 채널에 절대 내보내지 않는다.
그룹 채팅에서는 사용자의 대변인처럼 말하지 않는다.
확신이 없으면 아는 척하지 말고 확인 범위를 먼저 제시한다.
이런 규칙이 중요한 이유는 에이전트가 대체로 친절하고 낙관적으로 훈련되어 있기 때문입니다. 친절함은 장점이지만, 운영에서는 가끔 사고의 출발점이 됩니다. 할 수 있을 것 같다와 지금 해도 된다는 전혀 다른 말입니다. AGENTS.md는 그 차이를 분명하게 만들어야 합니다.4
협업 규범까지 적어야 진짜 덜 피곤하다
많은 사람이 AGENTS.md를 보안 문서쯤으로 생각합니다. 하지만 실제 체감 품질을 크게 바꾸는 건 협업 규범입니다. 즉, 에이전트가 얼마나 눈치 있게 같이 일하느냐입니다.
예를 들면 이런 규칙입니다.
먼저 확인할 수 있는 것은 먼저 확인하고, 정말 필요할 때만 질문한다.
한 번에 끝낼 수 있는 일은 질문을 쪼개지 말고 처리한 뒤 보고한다.
그룹 채팅에서는 모든 메시지에 답하지 않는다.
장시간 작업에서는 중간 상태를 파일로 남긴다.
긴 작업 뒤에는 다음 세션을 위한 핸드오프를 기록한다.
이 규칙이 없으면 에이전트는 열심히는 하는데 같이 일하기 피곤한 동료가 됩니다. 사소한 질문을 다 던지고, 채팅방에서 말이 많고, 중요한 결정을 대화창 어딘가에만 남겨둡니다. 반대로 협업 규범이 잘 적혀 있으면 에이전트는 조용히 필요한 일을 처리하고, 중요한 순간에만 존재감을 드러냅니다. 딱 일 잘하는 선배 같은 느낌입니다.34
USER.md는 사용자 자서전이 아니라 작업 브리프다
USER.md는 에이전트가 섬겨야 할 사람을 이해하는 문서입니다. 여기서 중요한 건 감동적인 자기소개가 아니라, 매일 판단에 실제로 쓰이는 정보입니다.36
좋은 USER.md에는 대개 이런 내용이 들어갑니다.
이름과 호칭
시간대와 활동 시간
기술 수준과 익숙한 도구
현재 집중하는 프로젝트와 우선순위
커뮤니케이션 취향
싫어하는 응답 방식
예를 들어 사용자가 한국 표준시 기준으로 움직이고, WSL과 터미널은 익숙하지만 리눅스 내부 구조 설명은 쉽게 듣고 싶어 한다면 그 정보는 매우 중요합니다. 같은 답이라도 훨씬 맞춤형으로 바뀌기 때문입니다. 반대로 취미의 역사, 학창 시절 이야기, 지금 당장 쓰이지 않는 배경정보는 토큰만 먹고 행동은 잘 안 바꿉니다.16
USER.md는 특히 시간 관련 업무에서 강력합니다. 일정, 리마인더, 아침 브리핑, 마감 계산은 시간대가 어긋나는 순간 전부 어색해집니다. OpenClaw는 설정에서 사용자 시간대를 다룰 수 있으므로, USER.md의 실제 생활 패턴과 시스템 시간대 설정을 함께 맞춰 주는 편이 좋습니다.1
좋은 USER.md는 취향보다 의사결정 기준을 담는다
초보자는 USER.md에 말투 취향만 적기 쉽습니다. 물론 그것도 필요합니다. 하지만 진짜 중요한 건 사용자가 어떻게 판단하는 사람인지입니다.
예를 들어 아래 차이는 큽니다.
빠른 실행을 선호하지만 대외 발신은 신중하다.
매출에 가까운 일을 성장 실험보다 우선한다.
설명은 짧게 받되, 리스크는 자세히 알고 싶어 한다.
코드는 완벽한 이론보다 당장 돌아가는 예제를 선호한다.
이런 정보가 있으면 에이전트는 단순히 말투만 맞추는 것이 아니라 추천의 방향까지 맞춥니다. 오늘 뭘 해야 하지?라는 모호한 질문을 받았을 때도 더 현실적인 답을 줄 수 있습니다. 같은 AI인데 유난히 나를 잘 아는 것처럼 느껴지는 순간은 보통 여기서 나옵니다.3
실전용 AGENTS.md 예시
혼자 사업을 운영하거나 작은 팀에서 OpenClaw를 쓰는 사람에게 잘 맞는 기본형 예시는 아래처럼 시작하면 좋습니다.
# AGENTS.md
## 세션 시작
- 시작 컨텍스트를 먼저 활용한다.
- 이미 제공된 정보를 불필요하게 다시 읽지 않는다.
- 오늘 해야 할 일과 열린 작업을 먼저 파악한다.
## 자율 실행
- 자료 조사, 요약, 초안 작성, 비파괴적 편집은 바로 실행한다.
- 명확한 버그 재현과 로그 확인은 바로 진행한다.
- 작업 중 중요한 결정은 기록 파일에 남긴다.
## 반드시 승인받기
- 외부 메시지 전송, 공개 게시, 결제, 배포
- 삭제, 대량 수정, 되돌리기 어려운 변경
- 전략 변경, 우선순위 대전환, 비용 증가
## 보안 경계
- 비밀, 토큰, 개인 정보를 외부로 내보내지 않는다.
- 파괴적 명령은 명시적 승인 없이는 실행하지 않는다.
- 그룹에서는 사용자의 입처럼 말하지 않는다.
- 확신이 없으면 추측 대신 확인 계획을 제시한다.
## 협업 규범
- 먼저 확인할 수 있는 것은 먼저 확인한다.
- 한 번에 끝낼 수 있는 일은 처리 후 보고한다.
- 복잡한 작업은 중간 상태를 파일에 남긴다.
- 다음 세션이 필요하면 핸드오프를 기록한다.포인트는 문장을 멋지게 쓰는 것이 아니라, 실제 행동이 떠오르도록 쓰는 것입니다. 읽자마자 아, 이럴 때는 먼저 하고 저럴 때는 물어보는구나가 보여야 합니다.
실전용 USER.md 예시
이제 같은 운영자에 대한 USER.md를 붙여 보겠습니다.
# USER.md
## 기본 정보
- 이름: 민준
- 호칭: 민준님
- 시간대: Asia/Seoul
- 주 활동 시간: 평일 09:00-22:00
## 현재 역할
- 1인 SaaS 운영자
- 제품, 마케팅, 운영을 혼자 맡고 있음
- 매출에 가까운 일이 최우선
## 기술 수준
- WSL, 터미널, Git 기본 사용 가능
- 프런트엔드와 자동화는 실용 예제를 선호
- 너무 깊은 인프라 설명은 쉬운 말로 풀어줄 것
## 소통 선호
- 결론 먼저
- 가능하면 다음 행동을 함께 제안
- 3개 이상 비교는 표보다 불릿 선호
## 싫어하는 것
- 검색하면 바로 알 수 있는 질문 되묻기
- 과한 칭찬이나 빈 인삿말
- 승인 없이 외부 발신하기이 정도면 충분히 강합니다. 특히 마지막 싫어하는 것 섹션은 생각보다 효력이 큽니다. 에이전트가 나를 불편하게 만드는 패턴을 미리 끊어 주기 때문입니다.3
두 파일이 함께 있으면 행동이 어떻게 달라질까
예를 들어 텔레그램으로 이런 메시지를 보냈다고 해봅시다.
오늘 오전 할 일 정리해줘. 그리고 고객 문의 답장도 초안 만들어 줘.
SOUL.md만 있는 에이전트는 친절하게 정리해 줄 수 있습니다. 하지만 AGENTS.md와 USER.md까지 잘 갖춘 에이전트는 훨씬 다르게 움직입니다.
먼저 USER.md를 보고 지금 사용자가 한국 시간으로 오전 업무를 시작했다는 걸 이해합니다. 그리고 매출에 가까운 일이 최우선이라는 맥락을 반영해 고객 문의를 상단에 둡니다. 동시에 AGENTS.md를 따라 외부 발신은 승인 대상이므로 답장을 바로 보내지 않고 초안만 만듭니다. 마지막으로 질문을 늘어놓기보다 먼저 할 일 정리와 초안을 만들어 보고합니다.
이 차이가 바로 흔들리지 않는 AI와 흔들리는 AI의 차이입니다. 전자는 규칙 속에서 자율적으로 움직이고, 후자는 매번 상황 따라 눈치를 새로 봅니다.
길게 쓰는 것보다 잘 나누는 것이 중요하다
처음에는 불안해서 뭐든 다 적고 싶어집니다. 하지만 AGENTS.md와 USER.md는 살찔수록 좋아지는 문서가 아닙니다. OpenClaw는 이 파일들을 컨텍스트에 매번 넣기 때문에, 너무 비대해지면 토큰을 많이 쓰고 잘릴 위험도 커집니다.15
그래서 다음 원칙이 좋습니다.
AGENTS.md에는 규칙과 절차만 둔다.USER.md에는 자주 쓰는 사용자 맥락만 둔다.오래 남길 사실과 학습 내용은 다음 장의
MEMORY.md로 보낸다.
쉽게 말해 AGENTS.md는 회사 운영 매뉴얼이고, USER.md는 대표님 업무 스타일 메모이며, MEMORY.md는 시간이 지나며 쌓이는 경험 노트입니다. 서랍을 나눠야 찾기도 쉽고, 고치기도 쉽습니다.
자주 하는 실수
이 장에서 가장 많이 나오는 실수는 대체로 비슷합니다.
SOUL.md에 승인 규칙과 사용자 정보를 다 몰아넣는다.AGENTS.md를 좋은 말 모음집처럼 쓴다.USER.md를 장황한 자서전으로 만든다.승인 기준을 모호하게 적어 에이전트가 매번 흔들린다.
파일을 바꿔 놓고 실제 테스트를 하지 않는다.
특히 안전하게, 적절히, 필요하면, 센스 있게 같은 단어는 위험합니다. 사람끼리도 애매한데, 에이전트에게는 더 애매합니다. 외부 발신 전 승인, 삭제 금지, 결론 먼저, KST 기준처럼 관찰 가능한 문장으로 바꿔야 합니다.
수정한 뒤 바로 해볼 테스트
문서를 저장했다면 곧바로 짧은 시나리오로 시험해 보는 편이 좋습니다.
고객에게 보낼 답장을 바로 전송하라고 시켜 본다.
모호한 일정 요청을 던져 시간대를 제대로 해석하는지 본다.
굳이 묻지 않아도 되는 간단한 작업을 맡겨 본다.
그룹 채팅에서 쓸 법한 문장을 던져 과하게 나서지 않는지 본다.
이 테스트에서 에이전트가 초안을 만들고 멈추는지, KST 기준으로 시간을 해석하는지, 쓸데없는 확인 질문을 줄이는지 보면 AGENTS.md와 USER.md가 살아 있는지 금방 알 수 있습니다. 안 되면 문서를 더 길게 쓰지 말고, 어긋난 행동을 정확히 막는 한 줄을 추가하면 됩니다.
흔들리지 않는 AI는 재능이 아니라 설계에서 나온다
많은 사람이 더 좋은 모델, 더 많은 스킬, 더 긴 프롬프트를 찾습니다. 물론 다 중요합니다. 하지만 실제 운영에서 신뢰를 만드는 건 늘 비슷합니다. 어디까지 알아서 움직이고, 언제 멈추고, 누구 기준으로 판단할지 분명한가.
AGENTS.md는 에이전트의 행동을 고정해 줍니다. USER.md는 그 행동의 방향을 사용자에게 맞춰 줍니다. 이 둘이 잘 써 있으면 에이전트는 매번 천재처럼 놀라운 답을 하지 않아도 됩니다. 대신 매번 비슷하게 괜찮은 판단을 합니다. 바로 그 안정감이 자동화를 오래 굴리게 만드는 힘입니다.
잘하는 AI는 한 번 감탄을 줍니다. 흔들리지 않는 AI는 매일 일을 끝냅니다.
다음 장에서는 이 안정적인 에이전트가 무엇을 어떻게 기억할지, 즉 MEMORY.md를 통해 맥락을 어떻게 쌓고 잊고 다시 불러오는지 살펴보겠습니다.
참고
3OpenClaw Workspace Files: SOUL.md, AGENTS.md and USER.md (2026)
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.