hhlee

2026-09-09 21:22:53

비하인드
에이전트를 위한 개발/운영 환경 설정하기

ChatGPT Image 2026년 9월 10일 오후 03_17_28.png

스튜에서는 에이전트 기반 코딩을 하기 위해 환경을 다음과 같이 설정하고 있습니다. 다만 AI 환경이 너무 급속도로 바뀌고 실제로 저희도 3개월~6개월 정도 지나면 사용패턴이 크게 바뀌기에, 이 글 자체의 유효성이 길지 않을 수 있습니다. 그래도 한 번 2026년 9월 어떻게 쓰는지 기록을 한 번 남겨보고자 합니다.

AI 에이전트를 여러 툴들 중 하나가 아니라, 이제 모든 업무를 하는 시작점이자 끝인 인터페이스로써 취급하고 있는 점이 중요할 듯합니다. 하고자하는 업무는 AI가 접근하고 조작 가능하도록 모든 업무(개발 및 테스트, 메뉴얼, 제한적 디비, 로깅, 모니터링, CS 대응)에 대한 접근 채널을 설정하고, 필요에 따라 업무를 배정하고 관리하도록 환경을 설정하는 것이 무엇보다 중요해진 시점이지요.

원격 개발 서버와 CLI 운용

개발 서버에 코드와 CLI 도구를 두고, 노트북이나 모바일 기기에서는 SSH로 접속해 작업합니다. 개발 서버와 내부 서비스에 대한 접근은 Tailscale 내부망을 활용합니다. 이렇게 하면 특정 PC에 개발 환경을 고정하지 않고 어디서든 같은 저장소와 실행 환경을 사용할 수 있습니다. 서버에서 Claude Code(이하 claude)나 Codex CLI(이하 codex)를 직접 실행하고, 수정 직후 개발 서버의 결과를 확인할 수 있다는 점이 가장 큰 장점입니다. 또한 24시간 가동되는 서버를 활용하면 스케줄링이나 반복 작업, 자동화 작업을 구성하기도 쉽습니다.

Bypass 또는 YOLO 모드

승인 프롬프트를 매번 확인하지 않고 명령을 연속 실행하는 `bypass permissions` 방식은 흔히 YOLO 모드라고도 부릅니다. 원격 개발 환경에서 반복적인 검색·테스트·로그 조회처럼 위험이 낮고 범위가 명확한 작업을 빠르게 처리할 때 유용합니다.

bypass를 사용하면 에이전트가 접근할 수 있는 범위가 크게 넓어질 수 있고, 실제 운영 서버나 인증 정보에 접근할 수 있는 상태에서는 실수의 영향 범위도 커집니다. 따라서 민감 파일 차단 훅·AWS 변경 전 확인·Cloudflare 인증 정보 접근 제한 같은 방어 장치를 함께 둡니다. 승인 절차를 줄이는 것과 모든 작업을 무조건 허용하는 것은 다른 문제로 취급해야 합니다.

파일 검색 향상을 위한 퍼지 검색 훅

최근에는 직접 파일을 언급하는 경우가 예전만큼 많지는 않지만, 파일 참조 기능은 여전히 필요합니다. 제가 사용해 본 환경에서는 Codex가 파일을 멘션할 때 원하는 짧은 경로를 비교적 정확하게 제안하는 반면, Claude의 기본 파일 후보 검색은 다소 답답하게 느껴졌습니다. 그래서 `.claude/settings.json`에서 `fileSuggestion`에 커스텀 스크립트를 지정해 사용하고 있습니다.

이 스크립트는 `git ls-files`로 추적 중인 파일만 검색하고, 파일명 앞부분과 짧은 경로를 우선 노출합니다. 검색어가 없으면 최근 변경 파일을 먼저 보여주며, 기본 검색보다 프로젝트 파일을 빠르게 찾을 수 있다는 장점이 있지만, 추적되지 않은 파일은 후보에서 빠지고 `fzf` 설치 권한이나 외부 의존성이 필요하다는 단점은 있습니다.

// 파일검색 로직 향상을 위한 프롬프트 예시

현재 저장소의 git tracked 파일만 대상으로 Claude Code 파일 추천 훅을 만들어줘. 파일명과 짧은 경로가 우선 노출되도록 퍼지 검색을 적용하고, 검색어가 없으면 최근 변경 파일을 먼저 보여줘. 외부 의존성이 없을 때의 폴백과`.claude/settings.json` 연결 방법도 함께 작성해줘.

환경변수와 credential 접근 제한

bypass 또는 YOLO 모드에서는 에이전트가 접근할 수 있는 파일 범위가 넓어질 수 있습니다. 이는 편의성과 맞바꾼 보안상의 위험입니다. 프로젝트에서 절대 노출되면 안 되는 `.env` 등의 환경변수가 대화에 섞여 들어가면 그대로 노출될 수 있기 때문에, 저희는 두 단계의 보안 규칙을 유지하고 있습니다.

먼저 전역 지침에는 에이전트가 `.env`, AWS 인증 정보, Cloudflare 설정, SSH 개인키, 토큰 저장소 등을 읽거나 출력하지 않는다는 규칙을 명시합니다. 예를 들어 실제 값이 들어 있는 `.env*`, `.aws/credentials`, `.cloudflared`, `.npmrc`, `auth.json` 같은 파일은 에이전트의 작업 범위에서 제외합니다. 필요한 값은 사용자가 직접 확인하고, 에이전트는 값이 노출되지 않는 identity 확인이나 공개 정보 조회만 수행합니다.

전역 지침을 설정해도 많은 경우 에이전트는 무시하고 필요하다고 판단하면 .env에 접근하려합니다. 따라서 기계적으로 중요한 경로가 채팅에 말려들어가는지를 점검하는 차단 훅이 필요합니다. `.claude/settings.json`의 deny 목록과 `block-credential-access.py`의 `PreToolUse` 훅이 파일 접근과 Bash 명령을 검사합니다. 환경변수 전체 출력, AWS Secrets Manager 복호화 조회, Lambda 환경변수 출력, `wrangler secret` 같은 명령은 차단하며, 차단 로그에는 `[CRED-GUARD]` 접두어를 붙입니다. `.claudeignore`에서도 환경 파일과 빌드 산출물, 캐시·업로드 디렉터리를 제외해 불필요한 컨텍스트 유입을 줄입니다.

이런 환경 보호 규칙을 직접 구성하고 싶다면, 에이전트에게 다음과 같이 요청할 수 있습니다.

// 차단 훅 생성을 위한 프롬프트 예시

현재 저장소의 `AGENTS.md`, `CLAUDE.md`, `.claude/settings.json`, `.claudeignore`와 기존 보안 훅을 먼저 읽고, 환경변수·credential 보호용 전역 지침과 `PreToolUse` 차단 훅을 만들어줘. 전역 지침에는 `.env*`, AWS·Cloudflare 인증 정보, 개인키·토큰 저장소의 읽기·출력·검색·수정을 금지하고, 환경변수 덤프·credential source·secret 인자 전달을 막는 원칙을 적어줘. `.claudeignore`는 접근 차단이 아니라 컨텍스트 제외용이라고 명시해. 훅은 `Read`, `Edit`, `Write`, `NotebookEdit`, `Grep`, `Bash`를 검사하고 민감 경로·출력 명령·파이프·리다이렉션·`git show` 등의 우회도 차단해줘. 차단 사유에는 `[CRED-GUARD]`를 붙이고 secret 값은 포함하지 않으며, 훅 오류 시 fail-closed로 처리해. 실제 credential은 열지 말고 가짜 경로와 명령으로 테스트한 뒤, 기존 설정을 보존하고 변경 파일과 검증 결과를 요약해줘.

가벼운 전역 지침과 계층적인 문서 구조

`AGENTS.md`와 `CLAUDE.md`는 사용하는 에이전트에 따라 프로젝트 작업의 기본 지침으로 자동 참조되는 문서입니다. 전역 지침에는 기술 스택, 반드시 지켜야 하는 보안 규칙, 코딩 규칙, 영역별 참고 문서의 위치만 둡니다.

만약 시간이 지남에 따라 전역 지침이 비대해지면(에이전트 스스로가 전역지침을 계속 추가), 중간에 한번씩 문서 분리가 필요한 사안인지 불필요한 지침인지 한 번씩 다이어트를 시킵니다. 결과적으로 이 전역 지침을 최대한 작게 유지하여 100 라인을 넘기지 않도록 합니다. 각 상황에서 항상 알아야 하는 것은 아닌 세부사항은 `docs` 폴더에 별도의 문서로 기술합니다.

예를 들어 다음과 같이 구성할 수 있습니다.

// AGENTS.md
- 결제 흐름은 결제 요청과 웹훅, 내부 상태 동기화로 구성되며 자세한 내용은 `docs/payments.md` 참조
- 로그는 개발 환경과 운영 환경의 저장·조회 방식이 다르며 자세한 내용은 `docs/logging.md` 참조

// docs/payments.md
# 결제 상세
결제 요청 → 외부 결제 승인 → 웹훅 검증 → 내부 구독 상태 반영
- 결제 상태가 변경되는 진입점
- 웹훅 재시도와 중복 처리 규칙
- 환불·취소·실패 상태의 처리 방법

// docs/logging.md
# 로깅 상세
- 개발 로그: 로컬 파일에서 확인
- 운영 로그: 중앙 로그 시스템에서 서버와 기능별로 조회
- 장애 조사: 사용자 식별자, 작업 ID, 발생 시각을 기준으로 관련 로그를 연결

위 예시는 구조를 설명하기 위한 일반적인 예입니다. 결제나 로깅과 관련되지 않은 업무에서는 해당 문서를 굳이 컨텍스트에 끌어들이지 않고, 각 작업에 꼭 필요한 문서만 접근하게 하여 토큰을 절약할 수 있습니다. 이러한 계층적 구조는 별도의 repository로 관리되는 운영 매뉴얼 등 문서 구조 전반에도 비슷하게 적용하고 있습니다.

자주 사용하는 스킬셋

커밋, 리뷰, Pull Request 생성, Git 작업 등 자주 사용하는 업무는 스킬로 분류합니다. 비디오스튜에서는 `cm`, `rv`, `pull-request`, `aws` 같은 스킬을 사용합니다. 스킬은 단순히 타이핑을 줄여주는 것을 넘어, 반복 작업의 절차를 고정하고 점진적으로 보완할 수 있게 해줍니다.

저희는 스킬을 두 가지 기준으로 생성하고 관리합니다. 첫째, 꼭 필요한 경우에만 직접 만듭니다. AI는 코드든 문서든 내용을 부풀려 만들어내기 쉽기 때문에, 인터넷에서 가져온 만능 스킬을 그대로 사용하지 않습니다. 필요한 업무의 방향성과 용도만 가지고 가장 단순한 형태로 시작한 뒤, 직접 사용하면서 예외 상황과 원칙을 더하고 빼며 프로젝트에 맞게 다듬습니다. 둘째, 빈도가 높은 업무만 스킬로 만듭니다. 스킬이 많아지면 초기 세션의 로딩과 추천 목록에도 부담이 생기므로, 빈도가 낮지만 반드시 알아야 하는 내용은 `docs`의 별도 문서로 관리합니다.

결국 스킬도 에이전트가 읽는 문서의 한 형태입니다. 별도의 `md` 문서라도 실행 방법과 판단 기준을 충분히 적어두면 실제 작업 결과는 스킬과 크게 다르지 않습니다. 차이는 주로 얼마나 자주 쓰는지, 얼마나 쉽게 발견하고 호출할 수 있는지에 있습니다.

인프라 CLI 연동

인프라 관리는 에이전트를 통해 대부분의 조회와 반복 작업을 수행할 수 있도록 구성합니다. AWS는 AWS CLI, Cloudflare는 Wrangler, Google Cloud는 Google Cloud CLI의 `gcloud` 명령을 사용합니다. 서버에 CLI와 인증 환경을 구성해두면 복잡한 백오피스의 수많은 옵션을 직접 찾아보는 부담을 줄이고, 원하는 작업을 자연어로 설명해 필요한 명령과 절차를 파악할 수 있습니다. 조회 가능한 트래픽·비용 지표를 바탕으로 예상 비용을 함께 검토할 수도 있습니다.

이는 특히 AWS를 사용할 때 유용합니다. Cloudflare의 대시보드는 비교적 간결하고 직관적이지만, AWS는 서비스가 매우 세분화되어 있어 기능과 옵션을 파악하는 데 많은 시간이 필요합니다. 에이전트가 관련 서비스와 설정의 관계를 함께 탐색해주면, 새로운 서비스를 일일이 공부해야 하는 부담을 줄이고 실제 작업에 집중할 수 있습니다.

다만 인프라는 실제 서비스에 직접적인 영향을 줄 수 있기 때문에, 전역 지침이나 관련 스킬에 변경 작업 전 사전 확인 절차를 반드시 두어야 합니다. 작업 목적, 수정 내용, 대상과 영향 범위를 먼저 확인한 뒤 실제 변경을 수행하는 방식입니다.

개발 및 운영 로그 시스템

로그는 개발할 때에는 디버깅 용도로, 운영 서버에서는 디버깅·통계·고객 문제 대응을 위해 꼭 필요합니다.

개발 서버에서는 외부로 로그를 전송할 필요가 없으므로 백엔드와 프론트엔드 로그를 파일로 저장합니다. 프론트엔드에서는 브라우저의 `console` 메서드를 후킹해 지정된 로깅 엔드포인트로 전송하고, 엔드포인트에서 로그 파일로 기록합니다. 백엔드는 프레임워크가 제공하는 기본 로깅 경로를 사용합니다. 그러면 에이전트가 테스트 중 발생한 로그를 직접 확인하고 즉시 보완할 수 있어, 개발자가 별도로 콘솔 로그를 복사해 전달할 필요가 줄어듭니다.

운영 서버에서는 클라이언트에서 발생한 오류를 별도의 수집 경로를 통해 Lambda 등의 수집 계층으로 전달한 뒤 CloudWatch에 저장하고, 백엔드에서는 syslog와 로그 에이전트를 통해 프레임워크의 오류를 CloudWatch Logs로 모읍니다. 로그 종류별로 어떤 CloudWatch 리소스에 저장되는지와 조회 방법을 전역 지침 또는 별도의 로그 문서에 기록해둡니다.

이렇게 활용할 수 있습니다.

“로그에 userId가 남아 있다면 특정 사용자의 오류를 검사해줘”
: 에이전트가 관련 로그 그룹과 스트림에서 해당 사용자의 기록을 검색하고, 발생 시각·빈도·요청 ID나 작업 ID를 기준으로 백엔드와 프론트엔드 로그를 연결합니다. 이후 호출 경로와 코드를 대조해 원인을 좁히고, 재현이나 추가 확인이 필요한지 판단합니다.

“최근 모니터링을 수행해줘”
: 마지막 확인 이후의 로그를 조회해 이미 알려진 반복 오류와 새로 발생했거나 빈도가 달라진 오류를 분리합니다. 새 오류는 발생 시각·횟수·영향 범위를 요약하고, 필요하면 관련 이슈 생성·코드 수정·추가 관찰 중 다음 조치로 이어갑니다.

오류 로그를 CloudWatch를 중심으로 통합 관리하면 여러 서버와 Lambda 등으로 기능이 분산되어 있어도 같은 방식으로 검색할 수 있습니다. 각 서비스의 로깅 방식과 콜스택이 달라도 중앙화된 로그를 기준으로 문제를 추적할 수 있기 때문에, 에이전트가 문제의 위치를 찾고 관련 코드를 대조하기가 쉬워집니다.

GitHub 이슈와의 연동

에이전트와 개발을 하다 보면 생각보다 많은 가지가 생성됩니다. A라는 문제를 파고들다 보면 숨겨져 있던 다른 문제, 먼저 풀어야 하는 선행 문제, 또는 해결은 했지만 나중에 로그를 모아 확인해야 하는 문제가 발견됩니다. 이럴 때 GitHub 이슈를 적극적으로 활용합니다.

언제든 자연스럽게 GitHub 이슈와 연동할 수 있도록 GitHub 이슈 관련 스킬(`/issue`)을 만들어두고, 개발 중 곁가지가 발견되면 이 스킬을 호출해 파생 이슈를 생성합니다. 이후 원래 문제 A에 다시 집중해 드릴다운을 이어갑니다. 파생된 이슈는 나중에 다시 확인할 수 있고, 해결되기 전까지 잊지 않고 대응할 수 있습니다. 하나의 문제에 집중하는 것은 에이전트의 컨텍스트를 유지하고 토큰 사용량을 줄이는 데도 도움이 됩니다.

많은 문제는 코드만으로 해결되지 않고 사용자의 데이터나 데이터베이스와 결합했을 때 다른 문제를 일으킬 수 있습니다. 개발 환경의 더미 데이터만으로는 측정하기 어렵고, 에러 레벨로 기록되지 않는 문제라면 영원히 묻힐 수도 있습니다. 이럴 때는 개발을 마친 뒤 관찰 기간과 판정일을 정한 `watch` 이슈를 만들거나, 기존 이슈에 관찰 계획을 추가합니다. 이슈 본문 첫 줄의 `Due:` 메타데이터와 라벨을 활용하면 확인 시점을 관리할 수 있습니다. 이후 “확인 기간이 지난 이슈를 검토하자”고 하면 수집된 데이터를 바탕으로 실제 해결 여부와 추가 수정 필요성을 판단할 수 있습니다.

기본모델과 자동 에스컬레이션

실제로 코딩이나 운영 업무를 하다보면 대다수는 에이전트를 인터페이스로 쓰는 경우가 많습니다. "~ 확인해", "~ 검사해", "~하자" 등등. 물론 같은 맥락에서도 갑자기 무거운 주제로 각잡고 봐야할 때도 있습니다. 이런 것을 감안했을 때 우리는 비용효율적으로 중간 모델을 기본값으로 설정합니다(claude라면 sonnet, codex라면 luna or terra).

이를 위해 전역 지침에서 하드한 작업의 경우에는 스스로 고수준의 모델을 서브에이전트로 호출하여 작업을 위임하도록 합니다(claude는 opus or fable, codex라면 sol high). 그러면 기본 모델은 일종의 라우팅 모델의 역할까지 겸하면서 밸런스 있게 상황에 맞는 모델을 쓰게 됩니다.

작업을 위임한다는것은 수정범위 파악, 계획서 작성을 맡기고, 서브에이전트가 계획서를 반환하면, 기본모델이 실제 코드작업을 진행하는 방식입니다. 물론 장점만 있는 것은 아닌데, 유일한 단점은 위임시 병목이 생기는 점, 고차원 모델로 가야하는 일을 자기가 엉망으로 할 때가 있는 점 등이 있습니다.

// 일상 업무
조사 중..
확인되었습니다.
이래저래해서 처리했습니다.
완료

// 복잡한 업무
조사 중..
지침에 따라 상위 모델에 위임합니다..
위임중..
서브에이전트가 계획중..
계획 완료
기본 모델이 받아서 코딩중..
완료

전역 지침에 고난도업무/보안/인증/디비스키마 변경로 예측시 위임, 혹은 진행에 시간이 오래 걸리거나 수정 범위가 커진 경우 중단하고 위임을 하도록 보완해주면 됩니다. 메인 에이전트(상위모델 위임,맥락 주입, 추후 코딩과 테스트)와 서브에이전트(계획)의 확실한 역할 분리를 지시하도록 하면 됩니다. 프로젝트마다 에스컬레이션 조건은 다를 수 있으므로 실제로 스킬을 사용해가면서 본인의 프로젝트 상황에 맞춰서 교정하면 됩니다.

※ claude의 경우 리스트에 없는 'opusplan'이라는 모델이 있어 일반 환경과 계획모드의 모델을 분리 지정이 가능합니다.

※ 처음부터 각잡고 봐야하는 업무는 애초부터 고차원 모델로 시작하기도 합니다.

운영메뉴얼 연동

환불 정책, 환불할 때 필요한 제반 사항, 계정에 관한 정책, 운영시 필요한 최소 지식 등등.. 서비스 내부 메뉴얼은 그 양이 방대하며, 사례가 생길 때마다 수시로 업데이트를 해야하는 특성이 있습니다. 또한 모든 팀원이 관여해야하기 때문에 정보 수정의 히스토리도 잘 갖추고 충돌이 없어야합니다.

저희는 운영메뉴얼을 별도의 git repository로 만들어서 수많은 md파일들의 구성으로 운영하고 있습니다. 최초 진입점인 README.md에는 각 영역별로 어떤 내용을 어떤 파일들이 정하고 있는지에 관한 게이트 역할을 합니다. 이 저장소는 일반 git cli 혹은 git mcp를 통해서 인증을 해놓고 스킬로 연결을 해놓았기 때문에(`/manual`), 언제든지 조회/수정이 에이전트 상에서 가능한 환경으로 해둡니다.

운영 : xx하고 yy할 때, 어떻게 해야하는거지? 
에이전트 :  검색 중.. 외부 서비스 연동에 관한 사안으로 파악됩니다. 문서에 따르면...

운영 : 결제 관련 zz하는 경우에 허용이 카드사에 따라 진행 불가한걸로 보완해
에이전트 : 검색 중.. 현재 aa하는 경우만 명시되어 있으며, 지시에 따라 zz하는 경우를 추가 보완하겠습니다.

※ 계층식 문서구조는 일반 지침도 그렇고 운영메뉴얼도 그렇고 많은 경우 반복되서 사용하고 있는 패턴입니다. 토큰 절약하면서도 효율적인 방법으로 적극 사용중입니다.

기타 사항들

Git worktree는 동일한 저장소에서 수정 영역을 구분해야 할 때 사용할 수 있습니다. 처음에는 동시에 여러 업무를 진행할 때 worktree 기능과 연동해 각각의 공간에서 작업했지만, worktree와 에이전트의 작업 위치를 맞추는 일이 생각보다 번거로워 지금은 자주 사용하지 않습니다. 다만 스킬들이 파일을 직접 건드려야하는 경우에는 워크트리에서 작업 후 폐기하도록 하는 경우 격리된 공간이 생겨 유용합니다.
과거에는 브랜치를 따서 작업했던 일도 에이전트 세션 안에서 대부분 한 번에 끝나기 때문에 예전만큼 브랜치를 많이 만들지는 않습니다. 그래도 작업 규모가 크고 많은 문서가 함께 바뀌는 경우에는 브랜치를 분리합니다. 정식 브랜치 흐름에 포함되지 않는 임시 브랜치는 작업이 끝나면 역할을 다하므로, 작업 중에는 `branch.md`를 만들어 브랜치의 목적·용도·지침을 기록하고 전역 지침에서 참조하도록 합니다.
에이전트의 메모리기능은 일부러 최대한 안 쓰고 있습니다. 눈에 보이지 않고 잘 관리되지 않는 지침이 들어가는경우 관리가 어렵기 때문에(또한 생성되는 메모리들은 단편적이고 핵심적이지 않은 경우가 많음), git 관리가 가능한 전역과 문서 형태로만 관리하는 것을 원칙으로하고 있습니다.

개략적인 에이전트 중심의 개발/운영에 관한 사안들로만 정리했습니다. 누락된 것들은 추후에 새로운 포스팅으로 개별 포스팅하도록 하겠습니다.

게시물로 이동