SOUL.md, AGENTS.md와 Agent workspace 파일
파일별 포맷·템플릿·수정 원칙은 Agent 설정 파일 안내에서 별도 페이지로 제공합니다. 이 페이지에서는 파일의 역할과 사용자가 변경할 수 있는 범위를 설명합니다.
Agent는 작업 공간의 지침과 기억을 업무에 활용할 수 있습니다. 파일마다 목적과 관리 경로가 다르며, 파일을 저장했다고 모든 대화에 자동으로 적용된다고 가정하지 마세요.
먼저 알아둘 점
- runtime 읽기 방식: 필요한 파일은 Agent 지침에서 읽도록 정하거나 filesystem MCP·CLI로 명시적으로 읽습니다. Cloud Portal은 session별 자동 주입 목록을 제어하지 않습니다.
- 자동 실행이 아님: 파일의 문장은 Agent의 지침과 맥락입니다. shell command, 외부 전송, 삭제 같은 행동을 파일에 적었다고 자동 실행되지는 않습니다. 지침 작성만으로 실행 승인과 접근 제한이 자동 강제되는 것은 아니므로 조직의 권한 정책을 함께 따라야 합니다.
- 길이 제한: 긴 bootstrap 파일은 context 한도 안에서 잘릴 수 있습니다. 핵심 규칙을 앞에 두고, 상세 절차는 별도 문서로 분리해
AGENTS.md에서 참조하세요. - 세션 기준: 변경한 내용은 이미 진행 중인 응답을 소급 변경하지 않습니다. Config 저장 뒤 재시작과 새 테스트 대화로 반영 여부를 확인하세요.
파일별 역할과 현재 설정 경로
| 파일 | 용도 | 관리 방법 |
|---|---|---|
SOUL.md | 역할, 말투, 행동 범위 | 에이전트 → 대상 Agent → 설정에서 편집·저장 |
AGENTS.md | 반복 업무의 지침과 기본 규칙 | Portal 직접 편집기가 없습니다. 허용된 작업 범위를 정해 Agent에게 요청합니다. |
TOOLS.md | 도구 사용 메모 | Portal 직접 편집기가 없습니다. 허용된 작업 범위를 정해 Agent에게 요청합니다. |
IDENTITY.md, USER.md | Agent 소개와 협업 선호 | Agent의 파일 접근 권한과 조직 정책을 따릅니다. |
MEMORY.md, memory/*.md | 장기 결정과 일별·주제별 기록 | 보존·삭제 범위를 정해 Agent에게 요청합니다. |
BOOTSTRAP.md | 처음 사용하는 작업 공간의 초기 안내 | 초기 설정이 끝난 뒤 처리 방법은 파일 안내를 따릅니다. |
HEARTBEAT.md | 주기 점검의 짧은 지침 | 해당 Agent에서 주기 점검이 실행되는지 먼저 확인합니다. |
SOUL.md 설정하기
- 에이전트에서 대상 Agent를 엽니다.
- 설정 카드를 펼친 뒤
SOUL.md미리보기를 읽습니다. - 수정으로 역할, 허용 범위, 금지 행동, 결과 형식을 수정합니다.
- 저장을 선택하고 저장 성공 메시지를 확인합니다.
- 미리보기를 다시 열어 Security Policy와 Sub-Agent Delegation 섹션이 유지되거나 추가됐는지 확인합니다.
- Agent 상태와 새 Room의 작은 읽기 요청으로 반영을 확인합니다. 성공 메시지만으로 restart 완료를 단정하지 말고 warning이나
restartFailed가 없는지 확인합니다.
저장 시 기본 보안·작업 위임 지침이 유지되거나 보완될 수 있습니다. 재시작 경고나 실패가 있으면 반영 완료를 단정하지 말고 Agent 상태와 새 대화에서 확인하세요.
추가 편집 도구가 표시되는 경우
설정 카드에 AI로 편집과 확장이 표시될 수 있습니다. 이 버튼이 없는 환경에서는 위의 수정 → 저장 절차를 사용하세요. AI로 편집한 내용을 적용하려면 먼저 변경 내용과 기존 지침의 보존 여부를 검토하고, 저장 뒤에는 위와 같이 Agent 상태와 반영 결과를 확인합니다.
AGENTS.md와 TOOLS.md는 어떻게 되나요?
새 Agent에는 기본 운영 지침이 제공될 수 있습니다. AGENTS.md와 TOOLS.md는 작업 공간의 문서이며, Agent가 허용된 파일 도구로 읽거나 수정할 수 있습니다. 기본 규칙을 검토하고 필요한 부분만 변경하세요.
중요한 차이:
SOUL.md는 runtime config가 제공하는 persona·보안 경계 파일입니다.AGENTS.md와TOOLS.md는 첫 boot 이후 workspace에 있는 운영 문서입니다.- 현재 Portal Config는
SOUL.md편집만 노출합니다.AGENTS.md또는TOOLS.md편집을 고객에게 제공되는 Portal 절차라고 안내할 수 없습니다.
운영 지침을 바꿔야 하는데 Portal에 편집 화면이 없다면, Agent에게 무분별하게 “모든 지침을 덮어써라”라고 요청하지 마세요. 변경 목적, 수정할 파일, 기존 규칙 보존, secret 금지, 검토자를 먼저 정하고 조직의 운영 담당자에게 변경 경로를 요청하세요.
어떤 내용을 어디에 둘까요?
| 필요 | 권장 위치 | 예 |
|---|---|---|
| 말투·역할·불확실할 때의 원칙 | SOUL.md | “배포 실패를 요약할 때 확정 사실과 확인 항목을 분리한다.” |
| 반복 업무에서 지켜야 할 작업 방식 | AGENTS.md | “외부 변경 전에는 승인 여부와 영향 범위를 확인한다.” |
| 특정 tool의 안전한 사용법 | TOOLS.md | “browser에서 고객 시스템을 열기 전 대상 계정을 확인한다.” |
| 사용자·팀의 비교적 안정적인 선호 | USER.md 또는 MEMORY.md | “응답은 한국어로, 요약 뒤에 확인 항목을 제시한다.” |
| 날짜별 조사 메모·긴 기록 | memory/*.md | “2026-08-05 배포 event 조사 메모” |
| 한 번만 할 onboarding | BOOTSTRAP.md | workspace 소개와 초기 확인 절차 |
Secret, password, API key, OAuth token, 고객의 불필요한 원문은 어느 workspace 파일에도 저장하지 마세요. Credential은 Credential 관리와 Secret과 민감한 값 다루기의 용도별 입력 경로로 관리합니다.
Agent에게 파일을 읽게 하거나 갱신하게 할 때
Agent에게 요청할 때는 대상 파일과 작업 범위를 명시하세요.
SOUL.md의 “결과 형식” 섹션만 제안해 주세요. 기존 보안 지침은 수정하지 말고, 변경 초안을 먼저 보여 주세요.
장기적으로 유지할 팀 선호를
MEMORY.md에 한 줄로 정리해 주세요. credential, 개인식별정보, 고객 원문은 기록하지 마세요.
이런 요청은 Agent가 필요한 파일을 읽고 쓰도록 유도할 수 있지만, tool policy와 Agent의 실제 권한이 허용해야 합니다. 사용자가 요청했다고 해서 파일 수정이 보장되는 것은 아니며, AGENTS.md·TOOLS.md·MEMORY.md는 현재 Portal에서 직접 검증할 수 없습니다. 중요한 변경은 조직의 운영 담당자가 제공하는 절차와 확인 산출물로 검토하세요.
확인 checklist
- 바꾼 파일이
SOUL.md인지 workspace 문서인지 구분했나요? - Portal에서 수정 가능한 경로인지, 관리자의 workspace 절차가 필요한지 확인했나요?
- security·secret 금지·tenant 경계를 약화하지 않았나요?
- Agent 상태가 안정된 뒤 작은 test Room으로 동작을 확인했나요?
- 긴 지침은 핵심만 workspace 문서에 두고 상세 문서를 참조하도록 했나요?