내 작업 폴더는 그대로, OpenCode는 별도 폴더에서 버그를 고친다

작업 폴더에서 변경을 절반쯤 작성했는데 날짜를 해석하는 코드에 오류가 접수됐습니다. 파일 편집은 이어가고 코딩 에이전트에는 별도 작업을 맡기고 싶습니다. 둘이 같은 폴더를 편집하기 시작하면 작은 수정이라도 진행 중인 내 변경과 구분하기 어려워집니다.

OpenCode 2.2.6은 11월 6일 스크립트에서 명령줄을 실행할 때 쓸 수 있는 워크트리 옵션을 추가했습니다. OpenCode는 대화형 터미널과 스크립트에서 프롬프트를 실행하는 별도 명령을 제공하는 오픈소스 코딩 에이전트입니다. 새 옵션으로 스크립트에서 별도 Git 워크트리를 만들어 작업을 시작할 수 있습니다. 이름도 선택할 수 있고, 원래 작업 폴더는 계속 쓸 수 있습니다. 같은 버전에서 설정이 일치하는 Model Context Protocol(MCP) 연결을 선택적으로 공유하는 기능도 추가됐습니다. 실행 전 두 가지를 확인할 이유가 생겼습니다. 에이전트가 어떤 파일을 바꿀 수 있고 어떤 서비스를 이용할 수 있을까요? OpenCode v2.2.6 릴리스 · OpenCode CLI 문서

작은 작업 하나에 예상할 수 있는 시작점과 변경을 살펴볼 위치를 정해 두면 유용합니다. 프로젝트 밖으로 나가는 동작에는 권한도 명시합니다.

OpenCode 프로젝트의 공식 터미널 화면에 패치와 세션이 보입니다. 버전이 지정된 브랜드 자료는 터미널 사용 경험을 보여줍니다. 이미지에는 MIT 라이선스 고지를 첨부했습니다. Telli.sh가 크기를 조정하고 여백을 넣었습니다.

별도 폴더에서 에이전트의 변경만 확인합니다

Git 워크트리는 작업마다 파일과 인덱스를 별도로 둡니다. Telli.sh 자체 제작.

Git 워크트리는 한 저장소에 작업 폴더 여러 개를 연결합니다. 연결된 워크트리마다 작업 파일, 인덱스, 현재 체크아웃 위치가 따로 있고 저장소 데이터 대부분은 공유합니다. 원래 수정한 파일을 그대로 둔 채 에이전트의 패치만 확인할 수 있습니다. 에이전트가 보는 소스 범위도 달라집니다. 같은 저장소에 연결됐다는 이유로 첫 폴더에서 커밋하지 않은 변경이 두 번째 폴더에 나타나지는 않습니다. Git 워크트리 문서

OpenCode의 11월 6일 릴리스에는 이 기능을 선택하는 세 가지 방식이 나옵니다. opencode run -w나 opencode run --worktree로 새 워크트리를 만들고, 이름을 붙이려면 --worktree=<name>을 사용합니다. 워크트리 옵션을 --continue나 --session과 함께 쓸 수 없다고도 명시합니다. 새 실행에는 새로운 시작 문맥이 필요합니다. 이미 긴 대화가 붙어 있는 버그라면 새 프롬프트에 필요한 재현 단계와 기대 결과를 옮겨 적습니다. OpenCode v2.2.6 릴리스 · 워크트리 구현과 예시

별도 폴더는 변경을 검토하는 공간입니다. 시작 전에 에이전트가 사용할 브랜치와 커밋을 적어 둡니다. 시작 뒤에는 생성된 워크트리의 커밋과 상태를 확인합니다. 테스트가 Git에서 추적하지 않는 파일이나 개발자 편집기에만 있는 변경에 의존하면, 두 실행 결과가 다른 이유를 시작점의 차이로 설명할 수 있습니다. 이전 코드에는 올바른 패치여도 지금 배포하려는 브랜치에는 맞지 않을 수 있습니다.

큰 변경을 맡기기 전에 작은 작업 하나를 시험합니다

직접 관리하는 저장소에서 범위가 분명한 작업을 고릅니다. 윤년의 2월 29일 테스트 실패는 예상 결과를 쉽게 확인할 수 있어 광범위한 업그레이드보다 첫 실험에 적합합니다. 경로 테스트 하나로 오래된 탐색 링크를 고치는 일도 비슷합니다. 바뀌어야 할 동작과 나중에 확인하는 방법을 명확하게 설명합니다.

1. 시작 상태를 기록합니다. 현재 폴더에서 git status --short와 git rev-parse HEAD를 실행합니다. 출력을 버그 보고서 옆에 보관합니다. 이미 통과하는 기준 테스트가 있다면 재현 방법을 적습니다. opencode --version으로 새 옵션을 제공하는 릴리스인지 확인합니다. OpenCode v2.2.6 릴리스

2. 이름을 정한 워크트리에서 작업 하나를 맡깁니다. 프롬프트에 재현 절차와 대상 테스트를 넣습니다. 다음 예시는 가상의 날짜 파서를 사용하며 저장소에 해당 테스트가 있다고 가정합니다. 변경을 커밋하지 말라고 요청하면 검토하기 쉽습니다. 더 강한 경계가 필요하면 권한과 실행 환경에서 적용합니다.

   Shell터미널에서 실행

   opencode run --worktree=date-parser "Reproduce the leap-day parsing bug in the date parser tests. Fix the narrow cause, run the targeted tests, and leave the changes uncommitted for review."
   

3. 결과를 살펴보기 전에 새 폴더를 찾습니다. 원래 저장소에서 git worktree list를 실행하고 표시된 경로를 사용합니다. 새 폴더에서 git status --short, git diff, git diff --cached를 확인합니다. 마지막 명령은 에이전트가 커밋 대기 상태에 올린 변경을 보여줍니다. 추적하지 않는 파일은 별도로 검토하세요. 에이전트 폴더에서 대상 테스트를 직접 다시 돌리고 윤년의 2월 29일과 그 날짜가 없는 해를 모두 검사하는지 확인합니다. Git 워크트리 문서

4. 검토한 변경만 가져옵니다. 검토한 커밋이나 패치를 목적 브랜치에 적용할 수 있을 때까지 변경을 분리해 둡니다. 원래 폴더의 상태도 다시 확인합니다. 필요한 내용을 기록하고 남겨 둘 미완료 변경이 없음을 확인할 때까지 에이전트의 워크트리를 보존합니다. Git의 워크트리 목록에서 어떤 폴더가 어느 작업에 속하는지 알 수 있습니다. Git 워크트리 문서

관련 없는 문제 두 개가 동시에 들어왔을 때도 같은 방식이 유용합니다. 각각 범위를 좁혀 주고 결과 변경을 모두 비교한 뒤 합칩니다. 워크트리를 나누면 한 에이전트의 미등록 테스트 변경이 다른 폴더에 나타나지 않습니다. 공통 코드를 수정했다면 같은 브랜치로 가져올 때 두 변경이 충돌할 수 있습니다. 브랜치 통합과 최종 회귀 검사는 평소의 검토 절차에서 진행합니다.

저장소 밖에서 누가 무엇을 할 수 있는지 정합니다

워크트리 두 개가 같은 운영체제 계정으로 실행될 수 있습니다. 같은 환경 변수, 인증 정보 관리 도구, 네트워크를 사용할 수도 있습니다. 새 워크트리 옵션은 실행 시작 위치를 정하고 작업 파일을 분리합니다. 더 강한 경계가 필요하다면 실행 환경이나 계정의 권한도 따로 제한합니다. 권한 확인 창은 그 규칙을 따르는 도구를 제어하고, 운영체제나 실행 환경은 프로세스가 실제로 접근할 수 있는 범위를 결정합니다.

변경 파일의 위치, 도구 승인, 실행 환경에서의 접근을 구분합니다. Telli.sh 자체 제작.

OpenCode V2 권한 문서는 개별 동작의 순서 있는 규칙을 설명합니다. 동작은 allow, ask, deny가 있으며 마지막으로 일치한 규칙이 우선합니다. 공식 예시 하나는 셸 명령을 실행하기 전에 확인하고, 일반 조회 명령은 허용하고, 원격 저장소에 변경을 올리는 명령은 차단합니다. 승인할 사람이 없는 실행이라면 반복 작업에 넣기 전에 그 환경에서 ask가 어떻게 동작하는지 시험하세요. 금지 항목은 설정에 명시하고, 작업에 꼭 필요한 서비스에는 유효기간과 권한이 제한된 인증 정보를 사용합니다. OpenCode 권한 문서

문서만 고치는 작업으로 이 계층을 시험할 수 있습니다. 예시 프로젝트에서 문서 한 구역만 바꾸도록 허용합니다. 사용이 허용된 모델 제공사를 지정하고 운영 인증 정보는 주지 않습니다. 스크립트를 돌려 패치가 예상 파일만 건드렸는지 확인합니다. 나중에 원격 저장소나 이슈 도구가 필요하다면 각각 필요한 이유를 정하고 권한을 따로 검증합니다.

같은 접근 범위에 있는 프로젝트끼리 연결을 공유합니다

MCP를 통해 문서 검색 서비스나 이슈 관리 도구처럼 다른 프로그램이 제공하는 기능을 에이전트가 사용할 수 있습니다. 11월 6일 릴리스에서 pool: true를 설정하면 한 OpenCode 서버에서 제공하는 여러 폴더가 관련 설정이 일치할 때 연결을 재사용할 수 있습니다. 공식 V2 문서는 프로토콜 2026-07-28 개정판부터 연결 공유가 적용된다고 설명합니다. 서버가 이전 개정판으로 협상하면 연결을 따로 둡니다. 같은 주소를 가리킨다고 설정이 일치하는 것도 아닙니다. 원격 설정과 인증 계정이 같아야 합니다. 로컬 서버에서는 실행 명령, 환경, 작업 폴더까지 일치해야 합니다. OpenCode v2.2.6 릴리스 · OpenCode MCP 연결 공유 문서

두 워크트리가 같은 계정으로 사내 문서 서비스를 조회한다고 합시다. 서비스가 해당 개정판을 지원하면 연결을 공유해 중복 설정을 줄일 수 있습니다. 두 폴더가 같은 자료에 접근해도 되는지, 연동이 필요한 기능만 제공하는지 먼저 확인합니다. 한 폴더에서는 공개 문서만 필요하고 다른 폴더에서는 사내 이슈도 열 수 있다면 연결을 분리해 범위를 확인하기 쉽게 유지합니다.

로컬 서버가 현재 작업 폴더에 의존할 수도 있습니다. 명령 문자열이 같더라도 프로젝트별로 실행한 프로세스가 서로 다른 로컬 문맥을 가질 수 있습니다. OpenCode 문서에 따르면 프로젝트 간에 로컬 연결을 공유하려면 작업 폴더를 고정해야 하며, 공유 연결에는 루트가 없습니다. 자신이 접근할 리소스를 명확히 보여주는 읽기 전용 서비스부터 시작할 이유입니다. 호출한 저장소에 따라 도구의 동작이 달라진다면 공유로 바꾸기 전에 달라지는 부분을 측정합니다. OpenCode MCP 연결 공유 문서

스크립트 실행도 어떻게 끝낼지 정해야 합니다

OpenCode 2.2.6은 --archived 옵션도 추가했습니다. 스크립트나 CI 세션을 처음부터 보관 상태로 열어 일반 세션 목록에 표시하지 않을 수 있습니다. 세션을 보여주는 방식의 변화입니다. 결과와 워크트리 경로, 테스트 결과는 검토자가 찾을 곳에 저장하세요. 일반 목록이 비어도 해당 패치를 찾을 수 있게 된 뒤 이 옵션을 사용합니다. 11월 6일 릴리스 노트에 따르면 --continue는 보관된 세션을 건너뜁니다. OpenCode v2.2.6 릴리스

같은 릴리스는 스크립트 실행이 끝나는 시점도 바꿨습니다. 프롬프트가 시작한 백그라운드 명령, 하위 에이전트, 이미지 작업이 끝날 때까지 기다립니다. 릴리스 노트는 내부 대기 시간 한도가 없다고 설명합니다. 개발 서버나 파일 감시기가 실행을 계속 붙잡을 수 있습니다. 자동 테스트에서는 검사가 끝나면 종료되는 명령을 쓰고, 이를 감싼 CI 단계에 시간 한도를 설정합니다. 취소된 실행, 실패한 테스트, 에이전트가 성공이라고 보고한 일을 구분합니다. 실행이 시간 초과되면 재시작하거나 합치기 전에 변경 상태를 직접 확인합니다. OpenCode v2.2.6 릴리스

파일럿이 동작하면 완료 보고 외에 실제로 시간을 아꼈는지 볼 수 있습니다. 새 실행을 준비하는 시간, 변경을 이해하고 검증하는 시간, 관련 없는 수정 복원이나 멈춘 도구 조사에 쓰인 시간을 살펴봅니다. 비슷한 크기의 작업을 여러 번 비교하세요. 별도 워크트리는 한 사람이 책임지고 볼 수 있을 만큼 패치를 작게 유지할 때 특히 유용합니다.

깨끗한 작업 폴더에서는 책임 범위가 보입니다

워크트리 옵션은 다른 개발자가 일을 이어가는 동안 검토자가 결과를 볼 명확한 시작점을 제공합니다. 기준 상태와 변경 내용을 확인하고 테스트를 다시 실행할 수 있습니다. 연결 공유와 실행 권한도 명확히 정하세요. 좋은 인수인계는 어디서 시작했고 무엇이 바뀌었으며 어떤 근거로 통합할 수 있는지 답하는 작은 패치입니다.

출처

• OpenCode 공식 터미널 화면 및 저장소 라이선스

• 2026년 11월 6일 OpenCode v2.2.6 릴리스

• OpenCode CLI 문서

• OpenCode V2 권한

• OpenCode MCP 연결 공유

• Git 워크트리 매뉴얼

---

작업에 얽힌 결정과 실험을 검색할 수 있게 정리하려면 Telli.sh 계정을 만들어 보세요.