[opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복] 6/12화: opencode 내장 툴 완전 가이드 — 파일·셸·검색·LSP 실전 활용

이 글은 「opencode 12일 집중」 6일차로, opencode가 제공하는 내장 툴을 하나씩 살펴보며 실전 활용법을 익힙니다.

어제 5일차에서 Plan 모드와 Build 모드를 Tab으로 오가며 “읽고 → 확인하고 → 고치는” 안전 루틴을 익혔습니다. 오늘은 그 Build 모드 안에서 AI가 실제로 코드를 다루는 손과 발 — 내장 툴을 파헤칩니다.

오늘의 핵심 3가지

• 파일 4총사 — read, write, edit, patch로 코드를 정밀하게 조작한다
• 셸·검색 콤보 — !command와 grep/glob으로 코드베이스 전체를 탐색한다
• LSP 연동 — 정의 이동·참조 검색을 AI가 직접 호출해 컨텍스트를 자동 수집한다

내장 툴이 중요한 이유

AI 코딩 에이전트의 핵심 차이는 “모델이 얼마나 똑똑한가”가 아닙니다. 모델이 얼마나 정확하게 코드베이스와 상호작용하는가입니다. 프롬프트에 파일 내용을 수동으로 복사해 붙여넣고, 결과를 다시 파일에 옮기는 시절은 지났습니다. opencode의 내장 툴은 AI가 파일 시스템, 셸, 언어 서버(LSP)를 직접 호출해서 작업을 완료합니다.

Claude Code나 Cursor도 비슷한 툴을 제공하지만, opencode는 오픈소스 특유의 투명성이 있습니다. AI가 어떤 툴을 호출했는지, 어떤 인자를 넘겼는지 TUI에 그대로 노출됩니다. 승인(y) 또는 거부(n)를 매번 선택할 수 있고, 5일차에서 다룬 Plan 모드로 먼저 계획을 세운 뒤 Build 모드에서 실행하는 흐름과 자연스럽게 결합됩니다.

파일 4총사 — read · write · edit · patch

opencode가 코드를 다루는 가장 기본적인 방법은 파일 도구입니다. 네 가지 도구가 역할을 나눠 맡습니다.

read — 파일 읽기

read는 지정한 파일의 내용을 AI의 컨텍스트에 올립니다. AI가 코드를 수정하기 전에 반드시 거치는 첫 단계입니다. 전체 파일을 한 번에 읽을 수도 있고, 줄 범위를 지정해 필요한 부분만 가져올 수도 있습니다.

# opencode 세션 안에서 자연어로 요청
> src/handler.go 파일의 50번째 줄부터 80번째 줄까지 읽어줘

# AI가 내부적으로 호출하는 툴
Tool: read
  file: src/handler.go
  offset: 50
  limit: 30

큰 파일을 통째로 읽으면 컨텍스트 윈도가 빠르게 소모됩니다. “이 파일에서 handleRequest 함수만 읽어줘”처럼 범위를 좁히는 습관이 토큰 비용과 정확도 모두에 유리합니다.

write — 새 파일 생성

write는 새 파일을 만들거나 기존 파일을 전체 교체합니다. 빈 프로젝트에 보일러플레이트를 생성하거나, 설정 파일을 처음 만들 때 주로 사용됩니다.

# 자연어 요청
> Go의 표준 프로젝트 레이아웃으로 cmd/server/main.go를 만들어줘

# AI 내부 동작
Tool: write
  file: cmd/server/main.go
  content: |
    package main

    import (
        "fmt"
        "net/http"
    )

    func main() {
        http.HandleFunc("/", handler)
        fmt.Println("Server starting on :8080")
        http.ListenAndServe(":8080", nil)
    }

    func handler(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "Hello, World!")
    }

기존 파일에 write를 쓰면 내용 전체가 대체되므로 주의가 필요합니다. opencode는 Build 모드에서 이런 동작을 실행하기 전에 승인 프롬프트를 띄워줍니다. 특히 기존 파일을 덮어쓸 때는 diff 미리보기가 함께 표시되므로 반드시 확인하세요.

edit — 정밀 수정

edit은 파일의 특정 부분만 교체합니다. 가장 자주 쓰이는 도구입니다. AI가 “이 줄을 찾아서 저걸로 바꿔라”는 식으로 동작하며, 나머지 코드는 건드리지 않습니다.

# 자연어 요청
> handleRequest 함수에서 에러 처리를 추가해줘. 
  500 에러일 때 로그를 남기도록.

# AI 내부 동작
Tool: edit
  file: src/handler.go
  old: |
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
  new: |
    resp, err := client.Do(req)
    if err != nil {
        log.Printf("request failed: %v", err)
        return fmt.Errorf("upstream request failed: %w", err)
    }
    if resp.StatusCode >= 500 {
        log.Printf("upstream returned %d", resp.StatusCode)
    }

edit의 핵심은 old 블록이 파일 안에 정확히 존재해야 한다는 점입니다. AI가 파일을 먼저 read하지 않고 edit을 시도하면 old 블록이 실제 코드와 달라 실패할 수 있습니다. 이런 경우 opencode가 에러를 반환하고, AI가 다시 read를 호출한 뒤 재시도합니다.

patch — 대규모 변경

patch는 unified diff 형식으로 여러 위치를 한 번에 수정합니다. 리팩터링처럼 파일 곳곳을 동시에 바꿔야 할 때 edit을 여러 번 호출하는 것보다 효율적입니다.

# 자연어 요청
> 이 파일의 모든 fmt.Println을 log.Printf로 바꾸고,
  import에 log 패키지를 추가해줘

# AI가 patch를 선택하는 경우
Tool: patch
  file: src/handler.go
  diff: |
    --- a/src/handler.go
    +++ b/src/handler.go
    @@ -3,6 +3,7 @@
     import (
         "fmt"
    +    "log"
         "net/http"
     )
    @@ -15,7 +16,7 @@
     func handler(w http.ResponseWriter, r *http.Request) {
    -    fmt.Println("request received")
    +    log.Printf("request received")
         // ...
     }

네 도구의 선택 기준을 정리하면 이렇습니다.

• read → 파일 내용을 컨텍스트에 올릴 때
• write → 새 파일을 만들거나 전체를 교체할 때
• edit → 특정 부분만 정밀 수정할 때 (가장 빈번)
• patch → 한 파일 안에서 여러 곳을 동시에 수정할 때

AI가 적절한 도구를 자동 선택하지만, 프롬프트에서 의도를 명확히 해주면 더 정확합니다. “이 함수의 리턴 타입만 바꿔줘”는 edit으로, “전체 파일을 새로 작성해줘”는 write로 자연스럽게 이어집니다.

셸 실행 — 느낌표 하나로 터미널 전체를

opencode의 두 번째 무기는 셸 명령 실행입니다. AI가 bash 도구를 통해 임의의 셸 명령을 실행할 수 있습니다. 테스트 실행, 빌드 확인, 패키지 설치, Git 작업 등 거의 모든 터미널 작업이 가능합니다.

기본 사용법

세션 안에서 자연어로 요청하면 AI가 적절한 명령을 구성해 실행합니다.

# 자연어 요청 예시
> 테스트를 돌려서 결과를 알려줘

# AI 내부 동작
Tool: bash
  command: go test ./... -v -count=1

# 결과가 AI 컨텍스트에 자동 반영
# 실패한 테스트가 있으면 AI가 원인을 분석하고 수정 제안

핵심은 AI가 명령 결과를 읽고 이해한다는 것입니다. 단순히 명령을 대신 타이핑해주는 게 아니라, 테스트 실패 메시지를 분석하고 → 관련 파일을 read하고 → edit으로 수정하고 → 다시 테스트를 돌리는 전체 루프를 자동으로 수행합니다.

실전에서 자주 쓰는 셸 패턴

# 빌드 확인
> 이 프로젝트를 빌드해봐
Tool: bash → go build ./...

# 린트 실행
> 코드 스타일 문제가 있는지 확인해줘
Tool: bash → golangci-lint run ./...

# 의존성 관리
> 새로 추가한 패키지의 의존성을 정리해줘
Tool: bash → go mod tidy

# Git 상태 확인
> 현재 변경된 파일 목록을 보여줘
Tool: bash → git status --short

# Docker 컨테이너 로그 확인
> 최근 에러 로그를 확인해줘
Tool: bash → docker logs --tail 50 my-service 2>&1 | grep -i error

셸 실행 시 승인 흐름

Build 모드에서 셸 명령은 파일 수정보다 더 높은 주의가 필요합니다. 파일 수정은 Git으로 되돌릴 수 있지만, 셸 명령은 되돌리기 어려운 부작용(파일 삭제, 네트워크 요청, 프로세스 종료 등)을 일으킬 수 있기 때문입니다.

opencode는 셸 명령 실행 전에 항상 승인 프롬프트를 띄웁니다.

┌─ Tool Call: bash ─────────────────────────┐
│ command: rm -rf ./build && go build ./... │
│                                           │
│ [y] Allow  [n] Deny  [a] Always allow     │
└───────────────────────────────────────────┘

• y — 이번 한 번만 허용
• n — 거부. AI가 다른 접근 방식을 시도
• a — 이 명령 패턴을 세션 동안 항상 허용

go test, npm run lint 같은 안전한 명령은 a로 자동 허용해두면 작업 흐름이 빨라집니다. 반면 rm, docker stop, git push 같은 명령은 매번 확인하는 편이 안전합니다.

검색 도구 — grep과 glob으로 코드베이스 훑기

대규모 코드베이스에서 AI가 올바른 파일을 찾는 것은 정확한 수정만큼 중요합니다. opencode는 두 가지 검색 도구를 내장합니다.

grep — 내용 검색

grep은 파일 내용을 정규식으로 검색합니다. “이 함수가 어디서 호출되는지”, “이 상수가 어디서 정의되는지”를 찾을 때 사용합니다.

# 자연어 요청
> handleRequest 함수가 호출되는 모든 위치를 찾아줘

# AI 내부 동작
Tool: grep
  pattern: "handleRequest"
  path: "."
  include: "*.go"

# 결과 예시
src/server.go:45: resp := handleRequest(ctx, req)
src/server.go:78: go handleRequest(bgCtx, asyncReq)
src/middleware.go:23: return handleRequest(c.Request.Context(), wrapped)

grep의 옵션을 프롬프트에 명시하면 더 정확한 결과를 얻습니다.

# 파일 타입 제한
> Go 파일에서만 "context.Background()" 사용을 찾아줘

# 특정 디렉토리 한정
> internal/ 디렉토리 안에서 TODO 주석을 모두 찾아줘

# 정규식 활용
> "err != nil" 뒤에 return이 아닌 다른 처리를 하는 패턴을 찾아줘

glob — 파일 이름 검색

glob은 파일 이름 패턴으로 파일을 찾습니다. 프로젝트 구조를 파악하거나, 특정 확장자의 파일 목록을 확인할 때 씁니다.

# 자연어 요청
> 이 프로젝트의 테스트 파일 구조를 보여줘

# AI 내부 동작
Tool: glob
  pattern: "**/*_test.go"

# 결과 예시
src/handler_test.go
src/server_test.go
internal/auth/token_test.go
internal/db/query_test.go

파일 구조 파악은 AI에게 컨텍스트를 제공하는 핵심 수단입니다. 새로운 프로젝트를 처음 열었을 때 “프로젝트 구조를 파악해줘”라고 요청하면 AI가 glob으로 전체 파일 트리를 수집하고, 주요 디렉토리와 파일의 역할을 추론합니다.

grep + glob 콤보 — 실전 탐색 워크플로우

실제 작업에서는 두 도구가 연쇄적으로 사용됩니다. 예를 들어 “미사용 함수를 찾아서 정리해줘”라는 요청에 AI는 이런 흐름을 탑니다.

# 1단계: glob으로 Go 소스 파일 목록 수집
Tool: glob → **/*.go (테스트 제외)

# 2단계: grep으로 함수 정의 찾기
Tool: grep → "^func " (exported 함수 목록)

# 3단계: 각 함수 이름으로 grep → 호출 횟수 확인
Tool: grep → "functionName" (정의 1회 + 호출 0회 = 미사용)

# 4단계: 미사용 함수를 edit/patch로 제거
Tool: edit → 해당 함수 블록 삭제

# 5단계: bash로 빌드 확인
Tool: bash → go build ./...

이 전체 과정이 하나의 프롬프트에서 자동으로 이뤄집니다. 사람이 할 일은 중간중간 승인 버튼을 누르는 것뿐입니다.

LSP 연동 — 언어를 이해하는 AI

여기가 opencode의 진짜 차별점입니다. grep은 텍스트 기반 검색이라 동명이인(같은 이름의 다른 심볼)을 구분하지 못합니다. User라는 이름이 struct 정의인지, 변수명인지, 패키지명인지 텍스트만으로는 알 수 없습니다.

LSP(Language Server Protocol)는 이 한계를 넘어섭니다. opencode는 프로젝트에 설치된 언어 서버를 자동으로 감지하고 연동합니다. AI가 LSP를 통해 다음을 직접 수행할 수 있습니다.

정의 이동 (Go to Definition)

# 자연어 요청
> handleRequest 함수의 정의를 찾아서 보여줘

# AI 내부 동작
Tool: lsp
  action: definition
  file: src/server.go
  line: 45
  character: 12

# 결과: src/handler.go:15 의 함수 정의로 점프
# AI가 자동으로 해당 위치를 read

grep이었다면 “handleRequest”라는 문자열이 포함된 모든 줄을 반환했을 것입니다. LSP는 정확히 그 심볼의 정의 위치만 반환합니다.

참조 검색 (Find References)

# 자연어 요청
> User 구조체를 사용하는 모든 곳을 찾아줘

# AI 내부 동작
Tool: lsp
  action: references
  file: internal/models/user.go
  line: 8
  character: 6

# 결과: 정확한 타입 참조 목록 (변수명 User, 패키지명 user 등은 제외)
internal/auth/middleware.go:34  → 함수 파라미터로 사용
internal/db/queries.go:67      → 반환 타입으로 사용
src/handler.go:89              → 변수 선언에서 사용
api/routes.go:12               → JSON 마샬링 대상

리팩터링에서 이 차이는 결정적입니다. 구조체 필드를 변경할 때 grep으로는 놓칠 수 있는 참조를 LSP는 정확히 잡아냅니다.

LSP가 활성화되는 조건

opencode가 LSP를 사용하려면 해당 언어의 언어 서버가 시스템에 설치되어 있어야 합니다. 주요 언어별 언어 서버는 다음과 같습니다.

• Go — gopls (Go 설치 시 함께 제공)
• TypeScript/JavaScript — typescript-language-server
• Python — pyright 또는 pylsp
• Rust — rust-analyzer
• Java — jdtls (Eclipse JDT Language Server)

# 언어 서버 설치 확인 (Go 예시)
which gopls
# /usr/local/bin/gopls

# TypeScript 언어 서버 설치
npm install -g typescript-language-server typescript

# Python 언어 서버 설치
pip install pyright

언어 서버가 설치되어 있지 않으면 opencode는 자동으로 grep 기반 폴백으로 전환합니다. LSP 없이도 작동하지만, LSP가 있을 때 정확도가 눈에 띄게 올라갑니다.

LSP + 파일 도구 연쇄 — 리팩터링 시나리오

LSP의 진가는 다른 도구와 결합할 때 드러납니다. “함수 시그니처를 변경하고 모든 호출부를 업데이트해줘”라는 요청을 예로 들어보겠습니다.

# 프롬프트
> CreateUser 함수에 context.Context 파라미터를 첫 번째 인자로 추가하고,
  호출하는 모든 곳을 업데이트해줘

# AI의 자동 워크플로우

# 1단계: LSP로 CreateUser 정의 위치 찾기
Tool: lsp (definition) → internal/db/queries.go:45

# 2단계: read로 현재 시그니처 확인
Tool: read → func CreateUser(name string, email string) (*User, error)

# 3단계: LSP로 모든 참조 찾기
Tool: lsp (references) → 7개 파일, 12개 호출부

# 4단계: 정의 수정
Tool: edit (internal/db/queries.go)
  old: func CreateUser(name string, email string) (*User, error)
  new: func CreateUser(ctx context.Context, name string, email string) (*User, error)

# 5~16단계: 각 호출부 수정
Tool: edit (src/handler.go)
  old: user, err := db.CreateUser(req.Name, req.Email)
  new: user, err := db.CreateUser(r.Context(), req.Name, req.Email)
# ... 나머지 11개 호출부도 동일하게 수정

# 17단계: 빌드 확인
Tool: bash → go build ./...

# 18단계: 테스트 실행
Tool: bash → go test ./... -count=1

사람이 수동으로 했다면 “찾기/바꾸기”로는 각 호출부의 컨텍스트 인자가 다르기 때문에 일괄 치환이 불가능했을 것입니다. AI + LSP 조합은 각 호출부의 맥락을 이해하고 적절한 컨텍스트 변수를 선택합니다.

실전 실습 — 처음부터 끝까지

지금까지 배운 도구들을 하나의 실습으로 묶어보겠습니다. 아래 명령어를 따라 하면 내장 툴의 연쇄 작동을 직접 체험할 수 있습니다.

준비: 실습 프로젝트 생성

# 실습용 Go 프로젝트 생성
mkdir -p ~/opencode-day6 && cd ~/opencode-day6
go mod init example.com/day6

# 간단한 HTTP 서버 코드 작성
cat > main.go <<'EOF'
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

var users = []User{
    {ID: 1, Name: "Alice", Email: "[email protected]"},
    {ID: 2, Name: "Bob", Email: "[email protected]"},
}

func getUsers(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(users)
}

func main() {
    http.HandleFunc("/users", getUsers)
    fmt.Println("Server starting on :8080")
    http.ListenAndServe(":8080", nil)
}
EOF

# opencode 세션 시작
opencode

실습 1: 전체 탐색 → 분석

# opencode 세션 안에서
> 이 프로젝트의 구조를 파악하고, 개선할 점 3가지를 알려줘

AI가 glob으로 파일 목록을 확인하고, read로 main.go를 읽은 뒤, 개선점을 분석합니다. Plan 모드(Tab)에서 시작하면 수정 없이 분석만 받을 수 있습니다.

실습 2: 기능 추가 (Build 모드)

# Tab으로 Build 모드 전환 후
> POST /users 엔드포인트를 추가해줘. 
  요청 본문에서 name과 email을 받아 새 User를 생성하고,
  201 Created와 함께 생성된 User를 반환해줘.
  에러 처리도 포함해줘.

AI가 read → edit(또는 patch) → bash(빌드 확인) 순으로 작업을 진행합니다. 각 단계마다 승인을 요청하므로 diff를 확인하면서 진행할 수 있습니다.

실습 3: 테스트 작성 → 실행 → 수정 루프

# 계속 Build 모드에서
> getUsers와 방금 추가한 createUser에 대한 테스트를 작성하고 실행해줘.
  실패하는 테스트가 있으면 코드를 수정해서 통과시켜줘.

이 프롬프트 하나로 AI는 다음을 자동 수행합니다.

1. write로 main_test.go 생성
2. bash로 go test ./... -v 실행
3. 실패 시 에러 메시지 분석 → edit으로 코드 수정
4. 다시 bash로 테스트 재실행
5. 모든 테스트 통과까지 반복

이 “작성 → 실행 → 실패 → 수정 → 재실행” 루프가 내장 툴 활용의 정수입니다.

내장 툴 조합 패턴 정리

실무에서 자주 등장하는 도구 조합 패턴을 정리합니다.

패턴 1: 버그 수정

bash(테스트 실행) → 실패 로그 분석
  → grep(에러 관련 코드 검색)
  → read(해당 파일 확인)
  → edit(버그 수정)
  → bash(테스트 재실행으로 확인)

패턴 2: 코드베이스 이해

glob(파일 구조 파악)
  → read(진입점 파일)
  → lsp/grep(핵심 함수의 호출 관계 추적)
  → read(관련 파일들 순차 읽기)

패턴 3: 대규모 리팩터링

lsp(심볼 정의·참조 전체 수집)
  → patch(정의부 수정)
  → edit × N(각 참조부 수정)
  → bash(빌드 + 테스트로 검증)

패턴 4: 새 기능 개발

glob + read(기존 코드 구조 파악)
  → write(새 파일 생성)
  → edit(기존 파일에 연결 코드 추가)
  → bash(빌드 + 테스트)
  → write(테스트 파일 생성)
  → bash(테스트 실행)

팁: 도구 사용을 프롬프트로 유도하기

AI가 어떤 도구를 사용할지는 프롬프트의 표현에 영향을 받습니다. 몇 가지 패턴을 알아두면 효율이 올라갑니다.

• “~를 찾아줘” → grep 또는 glob 유도
• “~의 정의를 보여줘” → lsp(definition) 유도
• “~를 사용하는 곳을 모두 찾아줘” → lsp(references) 유도
• “~를 수정해줘” → read + edit 유도
• “~를 새로 만들어줘” → write 유도
• “빌드/테스트해줘” → bash 유도
• “~를 수정하고 테스트까지 통과시켜줘” → 전체 루프 유도

“이 함수 어디서 쓰여?”와 “이 심볼의 모든 참조를 LSP로 찾아줘”는 결과가 다릅니다. 전자는 grep으로 텍스트 검색할 수 있고, 후자는 명시적으로 LSP를 타게 됩니다. LSP가 설치되어 있다면 후자가 더 정확합니다.

Gotcha 미니 코너 — 오늘의 함정

“AI가 read 없이 edit을 시도해서 실패하는 경우”

간혹 AI가 이전 대화에서 본 파일 내용을 기억하고, read 없이 바로 edit을 시도하는 경우가 있습니다. 그 사이에 다른 수정이 들어갔거나 파일이 변경됐다면 edit의 old 블록이 실제 파일과 달라 실패합니다.

해결법: 긴 세션에서 여러 파일을 동시에 작업할 때는 수정 전에 “먼저 이 파일을 다시 읽어줘”라고 한 줄 추가하세요. 또는 /compact 명령으로 컨텍스트를 정리한 뒤 작업을 이어가면, AI가 자연스럽게 read부터 시작합니다.

# 이렇게 하면 안전
> src/handler.go를 다시 읽고, handleRequest의 타임아웃을 30초로 변경해줘

# 이렇게 하면 간혹 실패
> handleRequest의 타임아웃을 30초로 변경해줘
# (AI가 이전에 읽은 오래된 버전으로 edit 시도)

이 패턴은 opencode뿐 아니라 Claude Code, Cursor 등 모든 에이전트에서 공통으로 나타나는 함정입니다. 파일 상태가 변했을 수 있는 시점에서는 항상 read 우선 습관을 들이세요.

내일 예고

내일 7일차에서는 AI의 행동 지침서 AGENTS.md를 작성합니다. 오늘 배운 도구를 AI가 언제, 어떻게 사용할지를 코드베이스 수준에서 규정하는 방법 — 프로젝트 컨벤션, 금지 패턴, 선호 라이브러리를 AGENTS.md에 적어두면 팀 전체가 일관된 AI 행동을 공유할 수 있습니다.

---