[opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복] 10/12화: opencode serve·run 자동화 완전 가이드 — 헤드리스 AI 코딩

「opencode 12일 집중」 10일차 — 비대화형 모드와 자동화

이 글은 「opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복」 시리즈의 10일차입니다.

어제 9일차에서는 MCP 서버를 연동해 opencode의 도구 범위를 외부 데이터·API까지 확장하는 방법을 살펴봤습니다. 오늘은 사람이 터미널 앞에 앉아 있지 않아도 opencode가 일하게 만드는 방법, 바로 비대화형(non-interactive) 모드입니다.

AI 코딩 에이전트의 진정한 가치는 사람이 타이핑하는 동안만이 아니라, 사람이 없을 때도 작동하는 자동화에서 나옵니다. 코드 리뷰를 밤새 돌리고, PR이 올라올 때마다 자동으로 분석하고, 배치 스크립트 안에서 AI 판단을 끼워 넣는 것 — opencode는 이 모든 시나리오를 이미 지원합니다.

오늘의 핵심 3가지

• opencode run — TUI 없이 프롬프트 하나를 보내고 결과만 받는 원샷 실행
• opencode serve — 백그라운드 HTTP 서버로 띄워 OpenAPI 스펙 기반의 헤드리스 자동화
• @opencode-ai/sdk — TypeScript/JavaScript에서 프로그래밍 방식으로 opencode를 제어하는 공식 SDK

왜 비대화형 모드가 필요한가

TUI는 개발자 한 명이 터미널 앞에서 작업할 때 최적화된 인터페이스입니다. 하지만 실무에서는 AI 코딩 에이전트가 필요한 순간이 훨씬 다양합니다.

• CI/CD 파이프라인 — PR이 올라올 때마다 코드 리뷰를 자동 실행
• 배치 스크립트 — 수십 개 파일을 일괄 리팩터링하거나 마이그레이션 코드 생성
• 크론 잡 — 매일 새벽에 의존성 업데이트 분석 보고서를 생성
• 웹 애플리케이션 백엔드 — 사용자 요청에 따라 AI 코드 생성을 서버 사이드에서 호출
• 챗봇·슬랙봇 통합 — 메시지가 들어오면 opencode에 위임해 코드 질문에 응답

이 모든 시나리오의 공통점은 터미널 UI가 없다는 것입니다. opencode는 이를 위해 세 가지 비대화형 인터페이스를 제공합니다.

1. opencode run — 원샷 실행의 기본

opencode run은 가장 단순한 비대화형 모드입니다. 프롬프트를 인자로 전달하면, opencode가 TUI를 띄우지 않고 결과를 stdout으로 출력한 뒤 종료합니다. 셸 스크립트나 파이프라인 안에서 AI 판단을 끼워 넣을 때 가장 먼저 쓰게 되는 명령입니다.

기본 사용법

# 가장 단순한 형태 — 프롬프트를 직접 전달
opencode run "이 프로젝트의 디렉터리 구조를 요약해줘"

# 파일 컨텍스트를 함께 전달 (@로 파일 참조)
opencode run "이 함수의 시간 복잡도를 분석해줘" @src/algo/sort.go

# stdin으로 프롬프트를 파이프
echo "package.json의 outdated 의존성을 정리해줘" | opencode run

# 특정 프로바이더·모델을 지정해서 실행
opencode run --provider anthropic --model claude-sonnet-4-20250514 \
  "이 코드의 보안 취약점을 찾아줘" @server/auth.go

opencode run의 핵심은 실행하고, 출력하고, 종료한다는 단순한 계약입니다. 별도 세션 관리나 상태 유지가 없으므로 스크립트 안에서 예측 가능하게 동작합니다.

-q 플래그 — 조용한 실행

기본 opencode run은 진행 상황(thinking, tool calls 등)도 함께 출력합니다. 스크립트에서 최종 결과만 필요할 때는 -q(quiet) 플래그를 붙입니다.

# 조용한 모드 — 최종 응답 텍스트만 stdout으로
opencode run -q "main.go의 TODO 주석을 모두 찾아 목록으로 출력해줘"

# 변수에 담아서 후속 처리
REVIEW=$(opencode run -q "이 diff의 코드 리뷰를 한 줄 요약해줘" @changes.diff)
echo "AI 리뷰 결과: $REVIEW"

-q를 붙이면 중간 과정의 스트리밍 출력이 모두 억제되고, 에이전트의 최종 답변 텍스트만 깔끔하게 나옵니다. grep, awk, jq 등 후속 파이프라인과 조합할 때 필수입니다.

-f json 플래그 — 구조화된 출력

사람이 읽을 텍스트가 아니라 프로그램이 파싱할 데이터가 필요할 때는 -f json을 씁니다.

# JSON 포맷으로 출력
opencode run -q -f json "src/ 디렉터리의 Go 파일 중 테스트가 없는 것을 찾아줘"

# jq로 특정 필드만 추출
opencode run -q -f json "이 함수를 분석해줘" @utils.go | jq '.response.text'

# 실전: CI에서 코드 품질 점수를 숫자로 추출
SCORE=$(opencode run -q -f json \
  "이 PR의 코드 품질을 1~10 점수로 평가하고 JSON {score: number, reason: string}으로 응답해" \
  @pr.diff | jq '.response.text | fromjson | .score')
echo "품질 점수: $SCORE"

JSON 출력에는 응답 텍스트뿐 아니라 사용된 모델, 토큰 수, 실행 시간 등 메타데이터도 포함됩니다. 자동화 파이프라인에서 비용 추적이나 성능 모니터링에 활용할 수 있습니다.

2. 실전 자동화 스크립트 패턴

opencode run은 단독으로도 유용하지만, 셸 스크립트와 조합하면 진정한 힘을 발휘합니다. 실무에서 바로 쓸 수 있는 패턴 몇 가지를 소개합니다.

패턴 1: Git 훅 — 커밋 전 AI 코드 리뷰

#!/bin/bash
# .git/hooks/pre-commit
# 스테이징된 변경에 대해 AI가 빠른 리뷰를 수행

DIFF=$(git diff --cached --diff-filter=ACMR)

if [ -z "$DIFF" ]; then
  exit 0
fi

echo "🔍 AI 코드 리뷰 실행 중..."

REVIEW=$(echo "$DIFF" | opencode run -q \
  "이 git diff를 리뷰해줘. 버그·보안 문제가 있으면 BLOCK,
   없으면 PASS로 첫 줄을 시작하고 이유를 간단히 적어줘.")

VERDICT=$(echo "$REVIEW" | head -1)

if echo "$VERDICT" | grep -q "BLOCK"; then
  echo "❌ AI 리뷰에서 문제를 발견했습니다:"
  echo "$REVIEW"
  echo ""
  echo "커밋하려면: git commit --no-verify"
  exit 1
fi

echo "✅ AI 리뷰 통과"
exit 0

패턴 2: 배치 리팩터링 — 여러 파일 일괄 처리

#!/bin/bash
# 모든 Go 파일의 에러 핸들링을 Go 1.22+ 패턴으로 업데이트

find src/ -name "*.go" -not -path "*/vendor/*" | while read -r file; do
  echo "처리 중: $file"

  opencode run -q \
    "이 Go 파일의 에러 핸들링을 Go 1.22+ errors.Join 패턴으로
     리팩터링해줘. 변경이 필요 없으면 그대로 두고." \
    @"$file"

  echo "완료: $file"
  echo "---"
done

echo "✅ 배치 리팩터링 완료"

패턴 3: 일일 보고서 — 크론 잡으로 자동 생성

#!/bin/bash
# crontab: 0 7 * * 1-5 /path/to/daily-report.sh
# 매일 오전 7시, 전일 커밋에 대한 AI 요약 보고서 생성

YESTERDAY=$(date -d "yesterday" +%Y-%m-%d)
TODAY=$(date +%Y-%m-%d)

COMMITS=$(git log --since="$YESTERDAY" --until="$TODAY" --oneline --no-merges)

if [ -z "$COMMITS" ]; then
  echo "어제 커밋 없음 — 보고서 건너뜀"
  exit 0
fi

DIFF=$(git diff "HEAD@{$YESTERDAY}" HEAD)

REPORT=$(echo "$DIFF" | opencode run -q \
  "다음은 어제($YESTERDAY) 발생한 코드 변경의 diff입니다.
   1) 주요 변경 요약 (3줄 이내)
   2) 잠재적 리스크 (있으면)
   3) 리뷰가 필요한 부분 (있으면)
   형식으로 보고서를 작성해줘.")

echo "## 일일 코드 변경 보고서 — $YESTERDAY" > "reports/$YESTERDAY.md"
echo "" >> "reports/$YESTERDAY.md"
echo "### 커밋 목록" >> "reports/$YESTERDAY.md"
echo "$COMMITS" >> "reports/$YESTERDAY.md"
echo "" >> "reports/$YESTERDAY.md"
echo "### AI 분석" >> "reports/$YESTERDAY.md"
echo "$REPORT" >> "reports/$YESTERDAY.md"

echo "✅ 보고서 생성: reports/$YESTERDAY.md"

3. opencode serve — 헤드리스 HTTP 서버

opencode run이 “한 번 실행하고 끝”이라면, opencode serve는 상시 대기하는 HTTP 서버입니다. opencode를 데몬처럼 백그라운드에 띄워 놓고, HTTP 요청으로 AI 코딩 작업을 요청할 수 있습니다.

서버 시작

# 기본 포트(3000)로 서버 시작
opencode serve

# 포트 지정
opencode serve --port 8080

# 백그라운드로 실행
opencode serve --port 8080 &

# 특정 모델을 기본값으로 지정
opencode serve --provider anthropic --model claude-sonnet-4-20250514 --port 8080

서버가 시작되면 http://localhost:8080에서 요청을 받습니다. opencode serve의 가장 큰 장점은 OpenAPI 스펙이 자동 제공된다는 점입니다.

OpenAPI 스펙 확인

# OpenAPI 스펙 조회
curl http://localhost:8080/openapi.json | jq .

# Swagger UI (브라우저에서 접속)
# http://localhost:8080/docs

OpenAPI 스펙이 있으므로 어떤 언어·프레임워크에서든 타입 안전한 클라이언트를 자동 생성할 수 있습니다. Python의 openapi-python-client, TypeScript의 openapi-typescript 등과 바로 연동 가능합니다.

HTTP API 직접 호출

# 세션 생성
SESSION_ID=$(curl -s -X POST http://localhost:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/project"}' | jq -r '.id')

echo "세션 ID: $SESSION_ID"

# 메시지 전송
curl -s -X POST "http://localhost:8080/sessions/$SESSION_ID/messages" \
  -H "Content-Type: application/json" \
  -d '{"content": "이 프로젝트의 아키텍처를 설명해줘"}' | jq .

# 세션 목록 조회
curl -s http://localhost:8080/sessions | jq .

# 세션 삭제
curl -s -X DELETE "http://localhost:8080/sessions/$SESSION_ID"

opencode serve의 세션은 TUI의 세션과 동일한 개념입니다. 세션을 유지하면 이전 대화 맥락이 보존되고, 새 세션을 만들면 독립적인 작업 공간이 생깁니다. 이를 통해 여러 프로젝트나 작업을 동시에 병렬 처리할 수 있습니다.

4. @opencode-ai/sdk — 프로그래밍 방식 제어

셸 스크립트와 curl만으로도 많은 것이 가능하지만, 복잡한 워크플로우를 구축할 때는 프로그래밍 언어의 타입 시스템과 에러 핸들링이 필요합니다. opencode는 공식 TypeScript/JavaScript SDK를 제공합니다.

SDK 설치

# npm
npm install @opencode-ai/sdk

# pnpm
pnpm add @opencode-ai/sdk

# yarn
yarn add @opencode-ai/sdk

기본 사용 — 세션 생성과 메시지 전송

import { OpenCode } from "@opencode-ai/sdk";

// opencode serve가 실행 중이어야 합니다
const client = new OpenCode({
  baseUrl: "http://localhost:8080",
});

async function analyzeCode() {
  // 세션 생성 — 프로젝트 경로를 지정
  const session = await client.sessions.create({
    path: "/path/to/my-project",
  });

  console.log(`세션 생성됨: ${session.id}`);

  // 메시지 전송 및 응답 수신
  const response = await client.sessions.sendMessage(session.id, {
    content: "src/server.ts의 에러 핸들링을 개선해줘",
  });

  console.log("응답:", response.text);

  // 세션 정리
  await client.sessions.delete(session.id);
}

analyzeCode();

스트리밍 응답 처리

import { OpenCode } from "@opencode-ai/sdk";

const client = new OpenCode({
  baseUrl: "http://localhost:8080",
});

async function streamAnalysis() {
  const session = await client.sessions.create({
    path: "/path/to/project",
  });

  // 스트리밍으로 응답 수신 — 실시간 진행 상황 확인
  const stream = await client.sessions.sendMessageStream(session.id, {
    content: "이 프로젝트의 테스트 커버리지를 분석하고 개선안을 제시해줘",
  });

  for await (const event of stream) {
    switch (event.type) {
      case "text":
        process.stdout.write(event.content);
        break;
      case "tool_use":
        console.log(`\n🔧 도구 호출: ${event.name}`);
        break;
      case "done":
        console.log("\n✅ 완료");
        break;
    }
  }

  await client.sessions.delete(session.id);
}

streamAnalysis();

실전 예제: PR 자동 리뷰 봇

import { OpenCode } from "@opencode-ai/sdk";

const client = new OpenCode({
  baseUrl: "http://localhost:8080",
});

interface ReviewResult {
  score: number;
  summary: string;
  issues: Array<{
    severity: "critical" | "warning" | "info";
    file: string;
    line: number;
    message: string;
  }>;
}

async function reviewPR(prDiff: string): Promise<ReviewResult> {
  const session = await client.sessions.create({
    path: process.cwd(),
  });

  try {
    const response = await client.sessions.sendMessage(session.id, {
      content: `다음 PR diff를 리뷰해줘.
응답은 반드시 아래 JSON 형식으로:
{
  "score": 1~10,
  "summary": "한 줄 요약",
  "issues": [
    {"severity": "critical|warning|info", "file": "파일명",
     "line": 숫자, "message": "설명"}
  ]
}

diff:
${prDiff}`,
    });

    return JSON.parse(response.text) as ReviewResult;
  } finally {
    await client.sessions.delete(session.id);
  }
}

// 사용 예
const diff = await fs.readFile("pr.diff", "utf-8");
const review = await reviewPR(diff);

console.log(`점수: ${review.score}/10`);
console.log(`요약: ${review.summary}`);

for (const issue of review.issues) {
  const icon = issue.severity === "critical" ? "🔴"
    : issue.severity === "warning" ? "🟡" : "🔵";
  console.log(`${icon} ${issue.file}:${issue.line} — ${issue.message}`);
}

// critical 이슈가 있으면 CI 실패 처리
if (review.issues.some(i => i.severity === "critical")) {
  process.exit(1);
}

5. CI/CD 파이프라인 통합

opencode의 비대화형 모드가 빛나는 가장 대표적인 장소는 CI/CD 파이프라인입니다. GitHub Actions를 예로 들어 봅니다.

GitHub Actions — PR 코드 리뷰 워크플로우

# .github/workflows/ai-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install opencode
        run: curl -fsSL https://opencode.ai/install | bash

      - name: Get PR diff
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > pr.diff

      - name: Run AI review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          REVIEW=$(opencode run -q -f json \
            "이 PR diff를 리뷰해줘. 
             중요도 순으로 최대 5개 피드백을 줘.
             형식: 번호. [severity] 파일:라인 — 설명" \
            @pr.diff)

          echo "$REVIEW" | jq -r '.response.text' > review.md

      - name: Post review comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 AI Code Review\n\n${review}`
            });

GitHub Actions — /opencode 이슈 코멘트 트리거

opencode는 GitHub Actions와의 통합을 위해 특별한 트리거도 지원합니다. 이슈에 /opencode로 시작하는 코멘트를 남기면 워크플로우가 자동 실행됩니다. 이 기능은 11일차에서 더 자세히 다루겠지만, 비대화형 자동화의 연장선으로 기본 개념만 짚고 넘어갑니다.

# .github/workflows/opencode-command.yml
name: OpenCode Command

on:
  issue_comment:
    types: [created]

jobs:
  run:
    if: startsWith(github.event.comment.body, '/opencode')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install opencode
        run: curl -fsSL https://opencode.ai/install | bash

      - name: Extract command
        id: cmd
        run: |
          BODY="${{ github.event.comment.body }}"
          CMD="${BODY#/opencode }"
          echo "prompt=$CMD" >> "$GITHUB_OUTPUT"

      - name: Run opencode
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          opencode run -q "${{ steps.cmd.outputs.prompt }}" > result.md

      - name: Reply with result
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const result = fs.readFileSync('result.md', 'utf8');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 OpenCode Result\n\n${result}`
            });

6. 아키텍처 패턴: serve를 활용한 마이크로서비스 통합

opencode serve를 상시 구동하면, 기존 백엔드 시스템에서 HTTP 호출 하나로 AI 코딩 능력을 활용할 수 있습니다. 몇 가지 아키텍처 패턴을 살펴봅니다.

패턴 A: 사이드카 — 기존 서비스 옆에 배치

# docker-compose.yml 예시
services:
  my-app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - OPENCODE_URL=http://opencode:8080

  opencode:
    image: node:20
    command: >
      sh -c "npm install -g opencode &&
             opencode serve --port 8080"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/workspace

이 패턴에서 my-app은 코드 분석이 필요한 순간마다 http://opencode:8080으로 HTTP 요청을 보냅니다. Docker 네트워크 안에서만 통신하므로 외부 노출 걱정이 없습니다.

패턴 B: 큐 워커 — 비동기 작업 처리

import { OpenCode } from "@opencode-ai/sdk";
import { Queue, Worker } from "bullmq";

const client = new OpenCode({ baseUrl: "http://localhost:8080" });

// 작업 큐 정의
const reviewQueue = new Queue("code-review");

// 워커 — 큐에서 작업을 꺼내 opencode로 처리
const worker = new Worker("code-review", async (job) => {
  const { projectPath, prompt, callbackUrl } = job.data;

  const session = await client.sessions.create({ path: projectPath });

  try {
    const response = await client.sessions.sendMessage(session.id, {
      content: prompt,
    });

    // 결과를 콜백 URL로 전송
    await fetch(callbackUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        jobId: job.id,
        result: response.text,
      }),
    });
  } finally {
    await client.sessions.delete(session.id);
  }
});

// 작업 등록 예시
await reviewQueue.add("review", {
  projectPath: "/workspace/my-project",
  prompt: "이 프로젝트의 보안 취약점을 스캔해줘",
  callbackUrl: "https://internal.example.com/webhook/review-done",
});

이 패턴은 코드 리뷰처럼 시간이 오래 걸리는 AI 작업을 비동기로 처리할 때 유용합니다. 요청자는 작업을 큐에 넣고 즉시 돌아가며, 결과는 웹훅으로 받습니다.

7. 프로덕션 운영 체크리스트

opencode serve를 실제 서비스 환경에서 운영할 때 고려할 사항을 정리합니다.

보안

• 네트워크 격리 — opencode serve는 localhost에만 바인딩하고, 외부 접근은 리버스 프록시(nginx 등)를 통해 제어
• API 키 관리 — 환경변수로만 주입. 코드·설정 파일에 하드코딩 금지
• 인증 추가 — opencode serve 자체에는 인증이 없으므로, 리버스 프록시에서 Bearer 토큰이나 mTLS를 적용
• 프로젝트 경로 제한 — 세션 생성 시 허용된 디렉터리만 접근 가능하도록 래퍼를 구현

리소스 관리

• 동시 세션 수 제한 — 각 세션은 LLM API 호출 비용과 메모리를 소비하므로, 최대 세션 수를 설정
• 타임아웃 — 장시간 실행되는 세션을 자동 종료하는 TTL 설정
• 비용 추적 — -f json 출력의 토큰 사용량을 집계해 일일 비용 알림

모니터링

# 헬스체크 스크립트 (크론에 등록)
#!/bin/bash
HEALTH=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/health)

if [ "$HEALTH" != "200" ]; then
  echo "opencode serve 다운 감지 — 재시작 시도"
  # systemd: systemctl restart opencode-serve
  # 또는 직접 재시작
  pkill -f "opencode serve" || true
  sleep 2
  opencode serve --port 8080 &
fi

systemd 서비스 등록 (Linux)

# /etc/systemd/system/opencode-serve.service
[Unit]
Description=OpenCode Headless Server
After=network.target

[Service]
Type=simple
User=opencode
WorkingDirectory=/opt/opencode
Environment=ANTHROPIC_API_KEY=sk-ant-xxxxx
ExecStart=/usr/local/bin/opencode serve --port 8080
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

# 서비스 등록 및 시작
sudo systemctl daemon-reload
sudo systemctl enable opencode-serve
sudo systemctl start opencode-serve

# 상태 확인
sudo systemctl status opencode-serve

# 로그 확인
journalctl -u opencode-serve -f

8. 조합의 힘 — run + serve + SDK 선택 기준

세 가지 비대화형 인터페이스 중 어떤 것을 쓸지는 상황에 따라 다릅니다.

시나리오	추천 인터페이스	이유
셸 스크립트·Git 훅·크론 잡	opencode run	프로세스 시작→종료가 명확, 상태 관리 불필요
CI/CD 파이프라인 단일 작업	opencode run -q -f json	JSON 출력으로 후속 처리 파이프라인 연결
웹 앱 백엔드 통합	opencode serve + HTTP	상시 대기, 세션 유지, 낮은 콜드스타트
복잡한 워크플로우 오케스트레이션	@opencode-ai/sdk	타입 안전, 에러 핸들링, 스트리밍 지원
다중 프로젝트 병렬 처리	serve + SDK 조합	세션별 독립 컨텍스트, 병렬 실행
빠른 프로토타이핑·일회성 분석	opencode run	추가 설정 없이 즉시 실행

일반적인 진화 경로는 이렇습니다: opencode run으로 시작해서 자동화의 감을 잡고, 호출 빈도가 높아지면 opencode serve로 전환해 콜드스타트를 줄이고, 복잡한 비즈니스 로직이 필요해지면 SDK로 이동합니다.

💣 Gotcha 미니 코너 — opencode run의 작업 디렉터리

opencode run은 현재 작업 디렉터리(cwd)를 프로젝트 루트로 인식합니다. CI 환경에서 actions/checkout 후 서브디렉터리로 cd한 상태에서 실행하면, opencode가 전체 프로젝트가 아닌 서브디렉터리만 보게 됩니다.

# ❌ 흔한 실수
cd packages/api
opencode run -q "프로젝트 구조를 분석해줘"
# → packages/api/ 만 보임, 모노레포 전체를 모름

# ✅ 올바른 방법
opencode run -q "packages/api/ 의 구조를 분석해줘" 
# → 프로젝트 루트에서 실행, 전체 맥락을 가진 상태에서 특정 디렉터리 분석

# ✅ 또는 serve를 쓸 때는 세션 생성 시 path를 명시
curl -X POST http://localhost:8080/sessions \
  -d '{"path": "/workspace/my-monorepo"}'

특히 모노레포에서 이 함정에 빠지기 쉽습니다. AGENTS.md가 프로젝트 루트에 있다면, 서브디렉터리에서 실행하면 AGENTS.md도 읽히지 않습니다. 항상 프로젝트 루트에서 실행하는 것을 기본 규칙으로 삼으세요.

마무리 — 사람이 없어도 돌아가는 코드

오늘 살펴본 opencode run, opencode serve, @opencode-ai/sdk는 opencode를 “개발자 옆의 도우미”에서 “인프라의 일부”로 승격시키는 도구입니다. AI 코딩 에이전트가 터미널 세션 안에서만 머물 이유는 없습니다. Git 훅에서, CI 파이프라인에서, 크론 잡에서, 백엔드 마이크로서비스에서 — 코드를 다루는 모든 자동화 지점에 opencode를 끼워 넣을 수 있습니다.

내일 11일차에서는 병렬 세션과 @general 서브에이전트, /undo·/redo, GitHub Actions 심화를 다룹니다. 여러 작업을 동시에 돌리고, 실수를 Git 기반으로 되돌리는 방법까지 — opencode의 멀티태스킹 능력을 파헤칩니다.

Photo by Diana ✨ on Pexels

---