한 줄 요약
OpenCode는 코드 탐색을 맡는 plan과 실제 수정을 맡는 build를 나눠 쓸 수 있는 오픈소스 코딩 에이전트입니다.
저장소: anomalyco/opencode
익숙하지 않은 코드를 맡으면 어디부터 읽어야 할지 막막합니다. 수정 요청은 한 줄인데 관련 파일은 여러 곳에 흩어져 있기도 합니다. 저희 주간 AI 브리핑에서 소개한 OpenCode가 궁금하셨다면, 작은 유지보수 작업 하나로 탐색과 수정 단계를 나눠 살펴보세요.
무엇을 할 수 있나
기본 에이전트인 build는 개발 작업을 위한 전체 접근 권한을 갖습니다. plan은 분석과 코드 탐색에 쓰며 기본적으로 파일 편집을 거절하고 bash 명령 실행 전 허가를 요청합니다. Tab 키로 둘을 전환할 수 있습니다. 복잡한 검색과 여러 단계 작업에는 @general 서브에이전트도 사용할 수 있습니다.
저희가 먼저 권하는 방식은 plan에서 근거를 읽고, 변경할 범위가 정해진 뒤 build로 넘어가는 것입니다. 에이전트가 제안한 설명과 실제 코드가 맞는지 살펴볼 여유를 두세요. 특히 기존 담당자에게 바로 물어보기 어려운 레거시 업무에서는 어떤 파일을 읽었는지도 함께 요청하면 검토할 출발점이 됩니다.
시작하기
npm으로 설치하려면 다음 명령을 사용합니다.
npm i -g @opencode/cli@latest
공식 설정 문서에서 모델 연결과 실행 환경을 준비하세요. README에는 Homebrew 등 다른 설치 경로도 있습니다. 팀에서는 설치 경로와 버전을 기록하고 업데이트를 검토할 담당자를 정해 두면 좋습니다. 모델을 연결할 때는 어느 공급사에 어떤 코드와 프롬프트를 보낼지 먼저 확인합니다.
활용 시나리오 1: 레거시 코드의 지도를 먼저 만들기
오래된 서비스에서 오류가 발생했는데 처리 흐름을 아는 사람이 없다면, 곧바로 수정을 요청하기보다 plan에서 입력과 출력이 이어지는 경로를 짚어 보세요. 다음처럼 요청해 볼 수 있습니다.
이 저장소의 주요 진입점과 데이터 처리 흐름을 설명해 주세요.
근거로 읽은 파일과 함수 위치를 함께 적고, 확인하지 못한 부분은 구분해 주세요.
파일은 수정하지 말고, 오류를 조사할 순서를 먼저 제안해 주세요.
응답을 받은 뒤에는 실제 파일을 열어 설명과 대조합니다. 서로 다른 기능을 한 흐름으로 묶었거나, 예외 처리를 건너뛰지 않았는지 확인하세요. 다음 담당자가 읽을 때 필요한 것은 긴 요약보다 어디를 근거로 삼았는지 알 수 있는 설명입니다. 구조 설명이 맞는지 확인한 다음 조사 범위를 좁히면 됩니다.
활용 시나리오 2: 작은 요구를 계획에서 변경으로 옮기기
목록 정렬이나 입력 검증처럼 범위가 작은 요구를 하나 골라 보세요. plan에서는 기존 동작과 바꿀 동작을 나란히 적도록 요청합니다. 사용자가 겪는 문제를 먼저 쓰고, 유지해야 할 조건을 함께 전달하는 것이 좋습니다.
입력값이 비어 있을 때의 처리를 개선하고 싶습니다.
현재 동작과 영향을 받는 부분을 찾아 설명해 주세요.
기존 정상 입력의 동작을 유지하는 작은 변경 계획과 검증 방법을 제안해 주세요.
계획을 검토한 뒤 Tab으로 build를 선택하고, 승인한 범위만 수정하도록 요청해 보세요. 여러 개선을 한꺼번에 끼워 넣기보다 동작 하나가 바뀌는 diff를 읽는 편이 검토하기 수월합니다. 결과에서는 요청한 조건이 코드에 반영됐는지, 관계없는 파일까지 바뀌지 않았는지 확인합니다.
활용 시나리오 3: 변경 후 설명과 검증을 함께 받기
수정이 끝났다고 검토가 끝나는 것은 아닙니다. 변경된 코드가 기존 호출부와 맞는지, 실제로 어떤 검증을 실행했는지 따로 요청해 보세요. 복잡한 검색에는 README가 안내하는 @general 호출을 활용할 수 있습니다.
@general 이번 변경을 사용하는 호출부와 관련 테스트를 찾아 주세요.
변경 전후 동작이 달라질 수 있는 경로를 정리하고,
실행한 검증과 아직 확인하지 못한 항목을 구분해 주세요.
리뷰에서는 변경 설명만 읽지 말고 diff와 검증 출력을 함께 봅니다. 실패한 검증이 있다면 변경 문제인지 실행 환경 문제인지 나눠 조사하세요. 저희는 처음부터 큰 기능을 맡기기보다 이런 작은 흐름을 반복하며 팀의 검토 기준을 맞춰 보시길 권합니다.
기업 도입에서 확인할 것
장점: 탐색과 수정을 나눠 코드 이해, 계획 검토, 실제 변경을 서로 다른 단계로 다룰 수 있습니다. 기존 저장소의 작은 유지보수 과제로 팀의 작업 흐름에 맞는지 살펴보세요.
운영 부담: 누가 build 전환을 허용하고 결과를 리뷰할지 정해야 합니다. 실패한 변경을 복구할 방법과 기존 검증 명령도 작업 전에 확인합니다.
보안: plan의 기본 동작만으로 호스트가 격리되는 것은 아닙니다. 접근할 파일과 실행 권한을 환경에서 제한하고 첫 시험에는 운영 자격증명이나 고객 데이터를 연결하지 마세요.
라이선스: 저장소는 MIT입니다. 수정·재배포 시 LICENSE를 확인하고, 연결한 모델과 외부 서비스의 이용 조건은 별도로 검토합니다.
원문과 함께 읽기
마치며
하이프마크 빌더 커뮤니티는 앞으로도 이렇게 직접 살펴본 AI 도구와 오픈소스를 꾸준히 공유하려고 합니다. 빌더 여러분께 도움이 될 좋은 자료들을 계속 모아 나누겠습니다.