클라우드 코딩 에이전트 실행 환경 만들기: 설정 파일 표준화와 시작 전 자가 점검 스크립트

로컬에서 에이전트 하나를 돌릴 때는 개발자 노트북만 맞으면 된다. 클라우드에서 에이전트를 병렬로 돌리면 매번 새로 만들어지는 임시 환경마다 같은 도구와 설정이 있어야 한다. 환경이 조금씩 다르면 에이전트가 실패했을 때 코드 문제인지 환경 문제인지 구분할 수 없다. 이 글은 환경을 설정 파일로 고정하고, 에이전트가 작업을 시작하기 전에 환경을 스스로 점검하게 만드는 방법을 정리한다.

로컬 환경을 그대로 옮기면 생기는 문제

Copilot cloud agent: copilot-setup-steps.yml

GitHub Copilot의 cloud agent는 임시 클라우드 환경에서 실행된다. 공식 문서에 따르면 .github/workflows/copilot-setup-steps.yml에 copilot-setup-steps라는 이름의 job을 두면 에이전트가 작업 전에 이 단계를 실행한다. 이 파일은 기본 브랜치에 있어야 적용되고, steps, permissions, runs-on(Ubuntu x64 또는 Windows 64-bit), services, timeout-minutes(최대 59) 등을 지정할 수 있다.

# .github/workflows/copilot-setup-steps.yml
name: Copilot setup steps
on: workflow_dispatch
jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_PASSWORD: postgres
        ports: ["5432:5432"]
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - name: 환경 점검
        run: node scripts/env-doctor.mjs
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

문서는 설정 단계 중 하나가 실패해도 에이전트가 그 시점의 환경으로 작업을 계속한다고 밝힌다. 그래서 점검 스크립트가 실패하면 에이전트의 작업 결과도 의심해야 한다. 점검 결과는 에이전트 세션 로그에 남으므로 실패한 PR을 볼 때 먼저 확인한다.

다른 에이전트·사람과 공유하는 devcontainer.json

Copilot 외의 에이전트나 Codespaces, 로컬 컨테이너에서도 같은 환경을 쓰려면 .devcontainer/devcontainer.json으로 정의한다. image는 기반 이미지, features는 추가 도구, postCreateCommand는 컨테이너 생성 마지막 단계에서 실행할 명령, containerEnv는 컨테이너 전체의 환경 변수다.

{
  "name": "agent-env",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:24",
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "containerEnv": {
    "NODE_ENV": "development"
  },
  "postCreateCommand": "npm ci && node scripts/env-doctor.mjs"
}

비밀값은 containerEnv에 직접 적지 않는다. 설정 파일은 저장소에 커밋되기 때문이다. 에이전트에 넘기는 비밀값의 범위를 줄이는 방법은 시크릿·.env 차단 설정에서 다뤘다.

시작 전 자가 점검 스크립트

에이전트가 환경 문제로 실패할 때마다 사람이 로그를 뒤지는 대신, 작업 전에 도구 버전, 필요한 환경 변수의 존재 여부, 외부 접속을 확인하고 실패하면 종료 코드 1을 반환한다. 비밀값은 존재 여부만 출력하고 값은 출력하지 않는다.

// 사용법: node env-doctor.mjs
// 에이전트가 작업을 시작하기 전에 환경을 점검한다. 비밀값은 존재 여부만 확인하고 값을 출력하지 않는다.
import { execSync } from 'node:child_process';

const REQUIRED_TOOLS = [
  ['node', ['--version'], '22.0.0'],
  ['git', ['--version'], '2.38.0'], // rebase --update-refs 사용
  ['npm', ['--version'], '10.0.0'],
];
const REQUIRED_ENV = ['DATABASE_URL', 'NPM_TOKEN'];
const REACHABLE = ['https://registry.npmjs.org/-/ping', 'https://api.github.com/zen'];

const ver = (s) => (s.match(/\d+\.\d+\.\d+/) || ['0.0.0'])[0].split('.').map(Number);
const gte = (a, b) => { for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i] > b[i]; } return true; };

let problems = 0;
const report = (ok, msg) => { if (!ok) problems++; console.log(`${ok ? 'OK  ' : 'FAIL'} ${msg}`); };

for (const [cmd, args, min] of REQUIRED_TOOLS) {
  try {
    // Windows의 npm은 npm.cmd라 셸이 필요하다. 인자는 고정 문자열이므로 한 줄 명령으로 넘긴다
    // (execFileSync + shell:true에 인자 배열을 주면 Node 24에서 DEP0190 경고가 난다).
    const out = execSync(`${cmd} ${args.join(' ')}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
    report(gte(ver(out), ver(min)), `${cmd} ${ver(out).join('.')} (필요 ${min} 이상)`);
  } catch {
    report(false, `${cmd} 없음`);
  }
}
for (const name of REQUIRED_ENV) report(Boolean(process.env[name]), `환경 변수 ${name} ${process.env[name] ? '설정됨' : '없음'}`);
for (const url of REACHABLE) {
  try {
    const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
    report(res.ok, `${new URL(url).host} 접근 HTTP ${res.status}`);
  } catch (err) {
    report(false, `${new URL(url).host} 접근 실패 (${err.cause?.code || err.name})`);
  }
}
console.log(problems ? `\n문제 ${problems}건 — 작업 전에 환경을 고치세요.` : '\n환경 점검 통과');
process.exitCode = problems ? 1 : 0;

2026-10-07에 Windows 11의 로컬 셸에서 실행한 결과다. 환경 변수를 설정하지 않은 상태라 두 항목이 실패했다.

$ node env-doctor.mjs
OK   node 24.15.0 (필요 22.0.0 이상)
OK   git 2.43.0 (필요 2.38.0 이상)
OK   npm 11.12.1 (필요 10.0.0 이상)
FAIL 환경 변수 DATABASE_URL 없음
FAIL 환경 변수 NPM_TOKEN 없음
OK   registry.npmjs.org 접근 HTTP 200
OK   api.github.com 접근 HTTP 200

문제 2건 — 작업 전에 환경을 고치세요.
exit=1

처음 버전은 execFileSync(cmd, args, { shell: true })로 도구를 호출했는데, Node.js 24에서 실행할 때마다 [DEP0190] DeprecationWarning: Passing args to a child process with shell option true 경고가 출력됐다. Windows의 npm은 npm.cmd라 셸이 필요한데, 셸 옵션과 인자 배열을 함께 쓰면 인자가 이스케이프 없이 이어 붙여지기 때문이다. Node.js 문서의 안내대로 명령 문자열을 직접 만들어 넘기도록 바꿨다. 이 스크립트의 인자는 고정 문자열이라 안전하지만, 사용자 입력이 들어가는 명령이라면 셸을 쓰지 않는 방식으로 바꿔야 한다.

도입 순서

1. 에이전트가 실패했던 사례를 모아 원인을 코드·환경·권한으로 분류한다. 환경 원인이 많다면 이 글의 순서를 적용한다.
2. 필요한 도구와 최소 버전, 환경 변수, 접속 대상을 점검 스크립트의 설정 배열에 적는다.
3. Copilot cloud agent를 쓴다면 copilot-setup-steps.yml에, 그 외에는 devcontainer.json의 postCreateCommand에 점검 스크립트를 연결한다.
4. 네트워크는 필요한 도메인만 허용하고, 비밀값은 플랫폼 시크릿으로 최소 범위만 주입한다.
5. 점검이 통과한 환경에서만 에이전트 결과를 리뷰 대상으로 삼는다.

에이전트 작업이 실패를 반복하며 비용을 쓰는 것을 막는 설계는 서킷 브레이커와 재시도 전략, 컨테이너 이미지를 개발·배포용으로 나누는 방법은 Docker로 AI 앱 환경 만들기에서 다룬다.