5 min read

OpenCode + 무료 LLM으로 코딩 에이전트 굴리기 — 매일 쓰는 실전 세팅 그대로

OpenCode 설치부터 지시서 작성 5원칙, 작업 기록 운용까지. 매일 쓰는 실전 세팅 그대로.

강의 커버

AI KOREA 24 무료 강의 01 · 초보자용 · 준비물 0원

이 강의에서 쓰는 방식은 실제로 매일 서비스 코드를 만지는 데 쓰는 그대로입니다.

이 강의에서 배우는 것

  1. OpenCode를 설치하고 무료 모델에 연결합니다.
  2. 에이전트에게 일을 시키는 "지시서"를 씁니다. 말로 시키는 것과 문서로 시키는 것은 결과가 다릅니다.
  3. 작업 기록(state.md) 운용으로 같은 일을 두 번 시키는 낭비를 없앱니다.

준비물

  • 컴퓨터 1대 (Mac·Windows·Linux 모두 가능)
  • Node.js (https://nodejs.org 에서 LTS 설치)
  • 비용 0원 — OpenCode 자체는 오픈소스이며, 시작은 무료 모델(Zen)로 충분합니다.

왜 이걸 배우나요

"AI에게 코딩 시켜봤는데, 시킨 것과 다른 걸 해놨다"는 경험이 있으실 겁니다. 문제는 AI 실력이 아니라 시키는 방식인 경우가 대부분입니다. 에이전트는 판단하지 않고 그대로 실행합니다. 애매하게 시키면 애매하게 움직입니다. 이 강의는 에이전트를 부하직원처럼 쓰는 법이 아니라, 정확한 작업 지시서를 쓰는 법에 대한 강의입니다.

1. OpenCode 설치하기

터미널을 열고 아래 중 하나를 실행합니다.

# 방법 A: 설치 스크립트 (권장)
curl -fsSL https://opencode.ai/install | bash

# 방법 B: npm
npm install -g opencode-ai

설치를 확인합니다.

opencode --version

버전이 출력되면 성공입니다.

무료 모델 연결하기

OpenCode는 어떤 LLM이든 연결할 수 있지만, 처음이라면 OpenCode Zen을 씁니다. OpenCode 팀이 직접 테스트한 모델 모음이라 설정이 가장 간단합니다.

  1. 작업할 프로젝트 폴더로 이동합니다.
  2. opencode를 실행합니다.
  3. /connect를 입력하고 안내에 따라 로그인합니다.

실습: 지금 바로 설치하고 opencode --version까지 실행해 보세요. 5분이면 됩니다.

2. 첫 작업 시키기 — 대화하듯, 그러나 정확하게

프로젝트 폴더에서 opencode를 실행한 뒤, 이렇게 시켜보세요.

나쁜 예: "이거 좀 고쳐줘"

좋은 예: "src/components/Header.astro 파일에서 모바일 화면(390px 이하)에서 메뉴 버튼이 겹치는 문제를 고쳐줘. 수정 후에는 npm run build가 성공하는지 확인해줘."

차이는 세 가지입니다. 대상 파일 지정, 문제 정의, 완료 기준. 이 세 가지가 빠지면 에이전트는 추측해서 움직이고, 추측은 대개 틀립니다.

실습: 자신의 프로젝트(없으면 빈 폴더에 테스트 파일 하나)에서 오타 수정 같은 작은 작업을 좋은 예 형식으로 시켜보세요.

3. 지시서 작성 5원칙 — 실전에서 굳어진 규칙

매일 쓰면서 굳어진 다섯 가지 원칙입니다. 이걸 지키는 것과 안 지키는 것은 결과물이 완전히 다릅니다.

원칙 1. 작업 전 관련 기록을 먼저 읽게 한다.

에이전트에게 "이 프로젝트의 docs/state.md를 먼저 읽고, 완료된 항목은 건드리지 마"라고 지시합니다. 기존 코드를 모르고 시키면 멀쩡한 것을 망가뜨립니다.

원칙 2. 모호한 표현을 금지한다.

"검토", "~하는 방향", "적당히" 같은 말은 지시가 아닙니다. 확정어로 씁니다. "버튼을 오른쪽으로 16px 옮긴다"처럼요.

원칙 3. 완료 기준을 명시한다.

"npm run build 성공", "모바일 390px에서 겹침 없음"처럼 무엇으로 잘됐는지 판단할지를 적습니다. 완료 기준 없는 작업물은 받을 수 없습니다.

원칙 4. 허용 범위와 실제 지시가 충돌하지 않는지 대조한다.

"이 파일만 고쳐라"고 해놓고 "전체 리팩터링해라"는 식의 모순이 없는지 읽어봅니다.

원칙 5. 공통 형식을 지킨다.

항목 ID, 한 줄 목표, 작업 경로, 허용 파일, 완료 기준, 종료 규칙. 형식이 같아야 나중에 기록을 찾아볼 수 있습니다.

실습: 위 5원칙에 맞춰 A4 반 페이지 분량의 지시서를 하나 써보세요. 주제는 아무거나(예: "블로그 글 목록에 날짜 표시 추가") 괜찮습니다.

4. 작업 기록 운용 — state.md

에이전트는 기억이 짧습니다. 그래서 작업 기록 파일을 둡니다. 방법은 단순합니다.

  1. 작업 시작 전, 기록 파일 맨 위에 진행 중 (날짜, 작업ID) 한 줄을 추가합니다.
  2. 작업이 끝나면 그 줄을 결과 요약으로 교체합니다.
  3. 자신의 옛날 진행 중 표식이 남아 있으면 지웁니다. 완료되지 않은 채 쌓인 표식은 상태를 오염시킵니다.

이렇게 하면 "어제 뭐 했지?", "이거 누가 고친 거지?" 같은 질문이 사라집니다. 여러 작업을 병렬로 돌릴 때 충돌도 막을 수 있습니다.

실제로 있었던 일입니다. 작업 완료 기록을 남기지 않는 에이전트가 디버깅을 하면서 250MB짜리 덤프 파일 5개를 남기고 갔습니다. 기록 규칙이 없으면 이런 일이 반복됩니다.

5. 검증 — 에이전트의 말을 믿지 않는다

에이전트가 "완료했습니다"라고 하면, 직접 확인합니다.

  • 빌드 명령을 직접 실행해 봅니다.
  • 브라우저에서 실제 화면을 봅니다.
  • 배포했다면 라이브 URL의 버전을 확인합니다.

"됐다는 말"이 아니라 "된 증거"를 봅니다. 이 습관 하나가 에이전트 활용의 성패를 가릅니다.

흔한 실수 Top 3

  1. "알아서 잘해줘" — 에이전트는 알아서 못 합니다. 시킨 것만 합니다.
  2. 기록 없이 작업 — 같은 작업을 두 번 시키고, 두 번 시간을 씁니다.
  3. 배포를 빼먹음 — 코드만 고치고 배포를 안 하면 사용자는 아무것도 못 봅니다. 지시서 마지막 단계는 항상 배포입니다.

정리

  • OpenCode 설치: npm install -g opencode-ai 또는 설치 스크립트
  • 지시는 대상·문제·완료 기준을 담아 정확하게
  • 지시서 5원칙과 state.md 기록 운용이 실전의 전부입니다
  • 완료는 말로 듣지 말고 증거로 확인합니다

다음 강의에서는 OpenCode의 무료 할당량이 떨어졌을 때 쓰는 무료 LLM 풀을 만듭니다. 직접 36개 모델을 호출해 측정한 성적표 그대로 공개합니다.

---

*AI KOREA 24 무료 강의 · Operated by 스타일팩토리9*

Continue reading