요즘 개발자들 사이에서 “그거 써봤어?”라고 묻는 그 도구
요즘 커피 타임이나 슬랙 채널에서 자주 들려오는 이야기가 있습니다. “이제 단순히 코드 짜주는 AI는 지겹다”는 탄식이죠. 사실 우리를 진짜 힘들게 하는 건 코드 한 줄 쓰는 게 아니라, 수정할 파일을 찾고, 터미널에서 테스트를 돌리고, 에러 메시지를 다시 복사해서 AI에게 갖다 바치는 그 ‘지루한 반복’이니까요.
이런 맥락에서 OpenCode(오픈코드)는 꽤 영리한 포지션을 잡았습니다. 웹 화면에 갇힌 채팅창이 아니라, 우리가 가장 시간을 많이 보내는 터미널(TUI) 안으로 직접 들어왔거든요. 오늘은 이 녀석이 단순한 보조 도구를 넘어 어떻게 우리 프로젝트의 ‘부사수’ 역할을 해내는지, 실전 워크플로우를 중심으로 짚어보려 합니다.
1. 첫 만남: 설치하고 내 프로젝트에 “인사”시키기
OpenCode는 “이 기능은 뭐야?”라고 묻기 전에, 이미 여러분의 프로젝트 디렉토리를 샅샅이 훑어볼 준비가 되어 있습니다. 설치는 아주 간단하지만, 그 이후의 ‘연결’ 과정이 훨씬 중요하죠.
터미널에서 한 줄로 시작하기
대부분의 현대적인 도구가 그렇듯, 복잡한 과정 없이 스크립트 한 줄이면 충분합니다.
- 공식 설치 스크립트:
curl -fsSL https://opencode.ai/install | bash명령어를 치면 끝납니다. 윈도우 사용자라면choco나scoop같은 패키지 매니저를 써도 좋고요.
어떤 뇌(LLM)를 쓸지 결정하기
설치가 끝났다면 프로젝트 폴더로 가서 opencode를 입력해 보세요. 하지만 바로 일을 시킬 순 없습니다. 이 에이전트가 어떤 인공지능 모델을 쓸지 정해줘야 하니까요.
- TUI에서
/connect입력: 이 명령어를 치면 API 키를 입력하고 모델을 선택하는 흐름이 나옵니다. 여기서 여러분의 취향이나 회사 정책에 맞는 모델을 연결하면 됩니다.
2. 프로젝트의 ‘헌법’ 만들기: /init과 AGENTS.md
제가 OpenCode를 쓰면서 가장 감탄한 지점은 단순히 파일을 읽는 게 아니라, “이 프로젝트의 룰”을 이해하려고 노력한다는 점입니다.
/init으로 시작하는 맥락 파악: 프로젝트 루트에서 이 명령을 실행하면 OpenCode가 폴더 구조를 스캔하고AGENTS.md라는 파일을 만듭니다.- 팀과 공유하는 가이드라인: 이 파일은 단순한 메모장이 아닙니다. “우리 팀은 테스트 코드를 어디에 짜는지”, “커밋 메시지 컨벤션은 어떤지”를 적어두면 에이전트가 그 규칙을 절대 어기지 않죠. 이걸 Git에 올려두면 팀원 전체가 같은 수준의 AI 어시스턴트를 갖게 되는 셈입니다.
3. 손에 익으면 무서운 TUI 실전 워크플로우
OpenCode를 제대로 쓴다는 건, 마우스를 건드리지 않고도 리팩토링과 테스트를 끝낸다는 뜻입니다. 여기서 핵심은 ‘@’와 ‘!’라는 두 개의 지팡이입니다.
파일과 터미널을 자유자재로 넘나들기
@파일명(퍼지 검색): 대화창에@를 치고 파일 이름 몇 글자만 적으면 에이전트가 그 파일 내용을 즉시 참조합니다. “이 로직이@auth.ts에 있는 거랑 충돌 안 날까?” 같은 질문이 가능해지죠.!로 시작하는 터미널 명령: “방금 고친 거 테스트 좀 돌려줘”라고 말할 필요가 없습니다.!npm test라고 치면 에이전트가 직접 명령어를 실행하고, 그 결과(에러 로그 포함)를 바탕으로 다음 해결책을 제시합니다.
“계획(Plan)은 신중하게, 실행(Build)은 과감하게”
가장 권장하는 흐름은 Tab 키를 활용하는 것입니다.
- Plan 모드: 먼저 무엇을 수정할지 계획만 세우게 하세요. “이 파일들을 고칠 거고, 이런 방식으로 로직을 바꿀 거야”라는 리포트를 먼저 확인하는 단계입니다.
- Build 모드: 계획이 맘에 든다면 Tab을 눌러 실행 모드로 바꿉니다. 이제 에이전트가 실제로 코드를 수정하기 시작하죠. 마치 운전대를 잡기 전 내비게이션 경로를 먼저 확인하는 것과 같습니다.
4. 전략적 선택: 이 도구가 정답은 아닐 수도 있습니다
물론 OpenCode가 모든 상황에서 정답은 아닙니다. VS Code나 Cursor 같은 IDE 내장형 도구들이 주는 시각적인 편안함도 무시할 수 없으니까요.
- OpenCode는 ‘편집의 자유’보다 ‘작업의 완결성’을 중시합니다. 터미널 안에서 빌드, 테스트, 수정이 한 흐름으로 이어지는 것을 선호하는 개발자에게는 천국이겠지만, 코드의 색상이나 세밀한 UI 편집을 중시한다면 답답할 수 있습니다.
- 보안 설정은 선택이 아닌 필수입니다. 에이전트가 내 파일을 마음대로 지우거나 위험한 쉘 명령을 실행하면 곤란하겠죠?
opencode.json설정에서permission.edit과permission.bash를"ask"로 설정해 두는 것을 강력히 추천합니다. 모든 행동 전에 “주인님, 이거 해도 될까요?”라고 묻게 만드는 안전장치죠.
5. 한 걸음 더: 팀의 생산성을 높이는 팁
조금 더 욕심이 난다면 Oh My OpenCode(OMO) 플러그인을 살펴보세요. 일종의 ‘플러그인 샵’ 같은 개념인데, 팀 단위로 공유하는 커스텀 기능을 추가할 수 있습니다. 다만, 여러 플러그인을 한꺼번에 켜면 충돌이 날 수 있으니 하나씩 적용해 보며 우리 팀에 맞는 최적의 조합을 찾아가는 과정이 필요합니다.
💡 바로 복사해서 써보는 실전 프롬프트
OpenCode에게 일을 시킬 때, 아래 템플릿을 참고해 보세요.
프로젝트 파악할 때: > “이 프로젝트의 전체 구조와 주요 실행 흐름을 요약해 줘. 엔트리 포인트가 어디고 설정 파일은 어디에 있지?”
리팩토링할 때 (Plan 모드에서):
“비즈니스 로직은 건드리지 말고 이 모듈의 가독성만 높여줘. 작업이 끝나면 테스트를 돌려서 결과를 보여주고.”
OpenCode는 단순히 똑똑한 도구가 아니라, 개발자의 작업 리듬을 깨지 않으려는 배려가 담긴 도구입니다. 창을 옮겨 다니느라 흩어졌던 집중력을 터미널 하나로 모으고 싶은 분들이라면, 오늘 바로 /init을 쳐보시는 건 어떨까요?