안전하고 확실한 구현, 실행(Execute) — permission 가드레일과 터미널 실행 제어

계획(Plan) 단계에서 구체적인 스코프가 확정되면, 실제 코드 작성과 명령을 수행하는 실행(Execute) 단계로 진입합니다. AI 에이전트가 터미널 쉘(Shell)을 직접 제어하여 코드를 수정하고 명령어를 실행할 때 가장 우려되는 점은 모델의 환각(Hallucination)이나 예기치 못한 오작동으로 인해 시스템에 파괴적인 변경(예: rm -rf, 강제 Push 등)을 가하는 것입니다.

open-code는 이를 방지하기 위해 Build/Plan 모드 분리, opencode.json 기반의 권한 제어(allow/ask/deny), 그리고 와일드카드 기반의 정밀 명령어 가드레일 체계를 내장하여 안전한 로컬 실행 환경을 제공합니다.

---

1. 실행(Execute) 단계의 핵심 철학

open-code가 지향하는 실행 단계의 핵심 철학은 "자율성과 통제권의 균형"입니다. 에이전트가 스스로 디렉토리를 탐색하고 빌드, 테스트를 수행하게 함으로써 개발 속도를 극대화하되, 시스템의 보안과 안정성을 위협하는 파괴적인 명령에 대해서는 명확한 물리적 제약(Guardrails)을 둡니다.

이를 실현하기 위한 open-code 실행 엔진의 3가지 대원칙은 다음과 같습니다. 1. 모드 기반 격리: 탐색 및 분석을 위한 Plan 모드와 실제 변경을 위한 Build 모드를 명확히 분리한다. 2. 최소 권한의 원칙: 에이전트가 접근할 수 있는 파일 경로(external_directory)와 쉘 명령어 영역을 최소화한다. 3. 명시적 사용자 동의: 위험할 수 있는 행위는 에이전트 세션 내에서 일회성(Once) 또는 지속성(Always) 승인을 거쳐서만 실행되도록 보장한다.

---

2. Plan vs Build 모드와 인터랙티브 권한 검증 흐름

open-code는 실행 위험성을 낮추기 위해 사용 환경과 목적에 맞춰 두 가지 실행 모드를 제공합니다.

• Plan Mode (계획/탐색 모드): 읽기 전용(Read-Only) 모드입니다. 에이전트는 코드베이스를 탐색하고 API 설계나 구현 계획을 세우는 데 전념합니다. 파일 변경이나 Bash 명령어 실행은 원천적으로 제한되거나 실행 전 반드시 명시적 승인을 필요로 합니다.
• Build Mode (구현/실행 모드): 활발히 코드를 작성하고 수정하는 모드입니다. 에이전트가 구성된 권한 규칙 범위 안에서 파일 생성/편집 및 빌드/테스트 명령어 실행을 자유롭게 수행할 수 있습니다.

에이전트가 특정 도구(예: bash 쉘 명령어 도구)를 통해 실행을 시도할 때, 내부 실행 엔진은 다음과 같은 3단계 Verifier 흐름을 거칩니다.

---

3. 대표 사례: opencode.json을 통한 가드레일 및 명령어 필터링 구현

실행 가드레일의 실제 구현체는 에이전트의 루트 또는 전역 설정 경로에 위치하는 opencode.json 파일입니다. 이 설정 파일은 에이전트의 자율적 쓰기 범위(edit, external_directory)와 터미널 명령어 실행 범위(bash)를 명확하게 제어하는 역할을 합니다.

1) 파일 시스템 접근 및 편집 제약 (external_directory)

에이전트가 프로젝트 외부에 있는 설정 파일이나 시스템의 민감한 경로를 침범해 수정하는 것을 방지하기 위해 파일 쓰기 경로를 격리합니다.

"permission": {
  "edit": "allow",
  "external_directory": {
    "/home/user/projects/*": "allow",
    "/home/user/knowledge-vault/*": "allow",
    "/home/user/.config/*": "allow",
    "/tmp/*": "allow",
    "*": "ask"
  }
}

• 특정 프로젝트 디렉토리나 샌드박스로 지정된 임시 폴더(/tmp) 하위 경로는 자유로운 수정을 허용(allow)합니다.
• 그 이외의 상위 시스템 디렉토리(*)에 접근해 쓰기를 시도할 경우, 반드시 사용자에게 질문(ask)하도록 설계되어 시스템 안전판 역할을 합니다.

2) 와일드카드 기반의 Bash 명령어 가드레일 (bash)

터미널 실행 단계에서 가장 중요한 안전장치는 에이전트가 실행하려는 쉘 명령어가 위험한 형태인지를 패턴 매칭으로 분석하고 필터링하는 것입니다.

"bash": {
  "rm -rf /*": "deny",
  "rm -rf ~*": "deny",
  "rm -rf *": "deny",
  "sudo rm -rf *": "deny",
  "git reset --hard origin/main*": "deny",
  "git push --force *main*": "deny",
  "chmod -R 777 *": "deny",
  "rm *": "ask",
  "pip uninstall *": "ask",
  "docker rmi *": "ask",
  "git reset --hard *": "ask",
  "git push --force *": "ask",
  "*": "allow"
}

• 차단(deny): 시스템 전체 삭제(rm -rf /*), 루트 또는 홈 폴더 삭제, 메인 브랜치에 대한 강제 덮어쓰기(git push --force *main*) 등 치명적인 명령은 매칭되는 즉시 실행을 거부합니다.
• 확인(ask): 파일 일부 삭제(rm *), 의존성 삭제(pip uninstall), 하드 리셋(git reset --hard) 등 개발 도중 발생할 수 있으나 확인이 필요한 명령은 사용자에게 판단을 넘깁니다.
• 허용(allow): 기타 일반적인 테스트, 의존성 설치, 린터 구동 등 빌드에 필수적인 명령어 집합(*)은 에이전트가 물어보지 않고 알아서 신속히 처리하도록 허용합니다.

---

4. 요약: 실행 단계가 주는 실질적인 효과

opencode가 내장한 실행 가드레일 정책은 다음과 같은 실질적인 효과를 만듭니다.

1. 안전한 로컬 개발: 샌드박스 또는 가상머신을 엄격하게 구축하지 않은 호스트 환경에서도, opencode.json의 보안 가드레일을 통해 에이전트의 실수로 인한 시스템 훼손을 차단할 수 있습니다.
2. 생산성과 안정성의 공존: 안전한 일상 빌드/테스트 명령어는 무중단으로 신속하게 수행하게 하고, 위험 명령만 선택적으로 사용자 개입(Once/Always)을 유도함으로써 AI 협업의 병목을 없앱니다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.