OpenCode 사용법 Tutorial: 코드 설명부터 기능 추가까지
OpenCode를 설치해 놓고 막상 실행하면 이런 느낌이 들곤 합니다.
“어… 이제 뭐라고 말하지?”
코드를 자동으로 설명해 준다는데, 어떤 형식으로 물어봐야 하는지,
기능을 추가해 달라면 어디까지 맡겨야 할지 감이 잘 안 잡히죠.
그래서 이번 글은 초급 개발자가 실제 프로젝트에서 바로 써볼 수 있는 기본 패턴 3가지,
즉 ① 코드 설명, ② 기능 추가, ③ 리팩터링을 중심으로 실습하려는 목적에 맞춰 구성했습니다.
설치는 지난 글에서 끝냈으니,
지금부터는 “실제로 어떻게 말해야 AI가 잘 도와주는가?” 여기에 집중합니다.
1. 프로젝트 폴더에서 OpenCode 실행하기
우선 연습용 프로젝트를 하나 준비해 둡니다.
예: 간단한 Python, Node.js 프로젝트 등 아무거나 괜찮습니다.
터미널에서 해당 폴더로 이동한 뒤 아래의 명령어를 실행합니다.
opencode첫 실행 시 TUI가 열리고, 기존 대화가 있다면 불러옵니다.
이제부터는 “대화 기반 개발환경”이라고 생각하면 이해가 쉽습니다.
2. 코드 설명 요청하기 — 가장 쉬운 출발점
AI에게 자연스럽게 말을 걸고 싶을 때, 가장 부담 없는 시작은 ‘설명해 달라’입니다.
例如
/ask 이 프로젝트의 전체 구조를 설명해줘.
/ask src/utils/date.py 파일의 역할을 알려줘.
/ask 이 함수가 어떤 의도를 갖고 작성된 건지 분석해줘.팁: 설명 요청 시 유용한 패턴 3가지
- “역할 중심 요약” 요청
- “이 파일들이 어떤 역할을 하는지 5줄로 정리해줘.”
- “흐름(Flow)” 요청
- “사용자가 버튼을 누르면 어떤 순서로 함수가 실행되는지 흐름을 알려줘.”
- “잠재적 위험성” 요청
- “이 코드에서 문제가 될 수 있는 부분을 3가지 찾아줘.”
왜 먼저 설명을 요청할까?
- 이 과정에서 OpenCode가 프로젝트 맥락을 파악합니다.
- 이후 기능을 추가하거나 리팩터링할 때 훨씬 안정적인 제안을 할 수 있습니다.
3. 기능 추가 요청하기 — 실제 개발자의 흐름 만들기
기능 추가는 “설명 요청 → 방향성 확인 → 구현 요청”의 패턴으로 진행하면 매우 안정적입니다.
단계 1: 방향성부터 AI와 합의하기
例如
/ask 현재 이 프로젝트에 "회원 가입 기능"을 추가하려면 어떤 파일을 수정해야 할까?AI coding agent 는 다음과 같이 답합니다.
- API 라우터 수정
- 스키마 추가
- DB 모델 확장
- 유효성 검사 로직 필요
이 단계에서 “내가 원하는 기능과 같은지”를 먼저 확인합니다.
단계 2: “초안” 구현 요청하기
/ask 회원 가입 API의 기본 형태를 만들어줘. 테스트도 같이 제안해줘.这样
- 엔드포인트 초안
- 异常处理
- 간단한 테스트 코드
등을 기본 골격으로 만들어 줍니다.
단계 3: 프로젝트에 반영하기
TUI 창에서 생성된 코드 블록 옆에는
“Apply changes (y/n)” 형태의 확인 옵션이 나옵니다.
- y → 실제 파일에 적용
- n → 다시 제안 요청
이렇게 하면서 구현과 검증을 반복합니다.
4. 리팩터링 요청하기 — 초급자가 가장 쉽게 성장하는 순간
리팩터링은 초급 개발자가 AI를 활용해 성장하는 데 가장 효과적인 영역입니다.
예: 파일이 너무 길어졌을 때
/ask 이 파일이 700줄이라 복잡해. 모듈을 어떻게 나누면 좋을까?예: 코드가 반복될 때
/ask 이 함수와 비슷한 패턴의 코드가 다른 곳에도 있어. 공통화할 방법을 제안해줘.예: 성능이 걱정될 때
/ask 이 부분의 시간 복잡도를 검토하고 개선 아이디어를 알려줘.리팩터링 시 좋은 전략 3가지
- “제안 먼저 → 구현 나중”
- “작게 쪼개서 요청하기”
- “자동 테스트 생성 요청하기”
例如
/ask 리팩터링을 진행하기 전에 자동 테스트 코드를 먼저 만들어줘.테스트가 생기면 변경 과정이 훨씬 안전해집니다.
5. terminal AI IDE 로서의 OpenCode 사용 팁
OpenCode는 단순한 챗봇이 아니라,
“코드와 파일을 직접 읽고 바꾸는 개발환경”에 가깝습니다.
따라서 다음 패턴을 익히면 생산성이 급격히 올라갑니다.
① 변경 범위 지정하기
/ask 이 파일의 120~180줄만 수정해서, 예외 처리를 더 단단하게 해줘.② 문서 작업 같이 시키기
/ask 방금 만든 API에 대한 문서 요약을 작성해줘. README에 들어갈 형식으로.③ 구현 후 테스트까지 묶어서 요청하기
/ask 방금 고친 기능을 검증할 테스트 코드 3개를 생성해줘.④ 변경 의도를 남기기 (commit 메시지)
/ask 이 리팩터링의 의도를 50자 이내 commit 메시지로 정리해줘.6. 초급 개발자를 위한 대화 템플릿 6종 (즉시 사용 가능)
1) 코드 이해
“이 부분이 무슨 역할인지, 5줄로 핵심만 설명해줘.”
2) 버그 추적
“예외가 발생했는데, 이 함수 호출 흐름을 분석해서 원인을 찾아줘.”
3) 기능 추가
“로그인을 지원하려면 어떤 파일을 수정하고 어떤 함수가 필요할까?”
4) 테스트 작성
“이 기능을 검증할 테스트 코드를 Python pytest 형식으로 3개 생성해줘.”
5) 리팩터링
“이 파일이 너무 길어. 모듈을 나누는 기준을 제안해줘.”
6) 문서 보완
“이 기능을 문서화한 요약을 작성해줘. README에 넣을 수 있게 정리해줘.”
초급 개발자는 이 템플릿 6개만 익혀도 AI와의 개발 대화가 훨씬 자연스러워집니다.
组织起来
이번 글에서는 OpenCode를 실제로 사용하는 흐름을
✔ 코드 설명 → ✔ 기능 추가 → ✔ 리팩터링이라는 3단 구조로 정리해 봤습니다.
이 도구의 핵심은 “AI와 대화를 주고받으며 점진적으로 개선하는 방식”입니다.
한 번에 완벽한 코드를 요청하는 대신,
설명 → 방향 협의 → 초안 → 반영 → 다듬기 과정을 반복하면 훨씬 안정적으로 사용할 수 있습니다.
다음 글에서는 드디어 oh-my-opencode 설치와 설정을 다루게 됩니다.
멀티 에이전트 환경에서 여러 모델을 팀처럼 쓰는 방법까지 이어질 예정이에요.
