실전/실무에서 바이브 코딩을 위한 환경 셋팅의 중요성

이제 수 많은 기업들이, AI를 활용한 회사의 변화를 꾀하고 있다. 그 중 정말 고민이 많은 회사 한 곳에서 DX와 AX로 전환을 하기 위한 작업이 의뢰가 왔는데, 무엇보다 회사의 상황을 제대로 이해 하는것이 매우 중요하다.

 

정말 열정도 있고, 앞으로 더욱 큰 중견기업으로 도약하기 위한 고민과 철저한 준비를 많이 하는 회사인것 같다.

일단 의뢰 받은 시스템은 5가지 정도 된다.

 

이러한 시스템들이 제대로 돌아가기 위해서는 최초 환경 설정이 매우 중요하다. 이 부분은 두번, 세번, 네번, 등등 하옇튼 많이 고민할 수록 나중에 시행 착오를 줄여줄 수 있기 때문에 매우 중요하다. 

 

intstructions.md 파일의 중요성이 여기 있다. 매번 시스템을 구축할때 마다 프롬프트를 길게 작성할 수 없기 때문에 모든 환경적인 셋팅은 이 파일에 넣어 주는것이 좋다. 

instructions.md 파일을 실행 한 모습임.

 

원래 이 디렉토리 안에는 아무런 파일들이 없었고, 딸랑 instructions.md 파일만 있었다. 그러나, 안티그라비티에게 instructions.md 파일을 주면서, 그 지시사항대로 일을 하라고 하면 위 와 같이 쫙 만들어 준다. 그리고 실제 docker 컨테이너 안에 띄울 수 있는 서비스 까지 docker-compose.yml로 만들어주고, .env 파일도 같이 넣어준다.

 

이를 이제 우리는 " docker-compose up -d --build" 만 dos창을 띄워서 이 명령어를 넣고, 엔터키만 누르면 된다. 이때는 당연히 내가 build up 할 디렉토리 안에 들어가서 해야 하겠지. 

 

그렇게 하면 Docker desktop을 들어가 보면 서비스 3개가 잘 떠 있다. 

3개의 서비스가 완벽하게 docker에서 돌고 있다.

 

이제 외부에서 localhost:8400 하고 브라우저에서 입력을 하면 당당히 서비스가 잘 될 것이다. 

이렇게 하면 기본적인 서버의 환경 셋팅은 끝난것이다. 

 

아래와 같이 instructions.md 파일의 내용을 보면 대충 이렇게 정리가 된다. 

# 프로젝트명 또는 회사명 ( 프로젝트명 또는 회사명 AX 전환) 프로젝트 인프라 및 기술 스택 명세서 ## 1. 핵심 기술 스택 (Tech Stack) --- 이곳은 데이터베이스 명, 어떤 Frontend Template를 사용할 것인지, UI는 또 어떤 툴을 사용할 것인지, 등등 정의 ## 2. 에이전트 구동 및 협업 프로세스 (Orchestration & Strict Token Control) 🔴 **본 프로젝트를 할당받은 메인 에이전트는 단독으로 모든 코드를 작성하지 않고, 반드시 아래의 '사령관 가이드' 및  '초강력 토큰 제어/리스크 제어 규칙'을 단 한 줄도 위반하지 않고 준수해야 한다. 이를 어길 시 즉시 작업을 무효화한다.** ### 2.1. 역할 분담 및 내비게이션 가이드 (Orchestration) 1. **[내장 툴 기반 코드그래프 매핑 (Internal Code Graph Indexing)]**:     - 에이전트는 새로운 기능을 구현하거나 코드를 수정하기 전, 무작정 다량의 파일들을 읽어 토큰을 낭비하지 않는다.     자신이 내장하고 있는 자체 분석 도구를 최초 1회만 구동하여 현재 프로젝트의 전체 구조를 인덱싱하고,     변경에 영향을 받는 파일만 정밀 타격하여 읽는다. * **🛡️ [DB-Prime] (데이터베이스 수석 아키텍트)**   * **임무**: 비동기/고속 처리에 최적화된 SQLModel 스키마 설계 및 Alembic 마이그레이션. Edge Worker 가상 제너레이터(Mock) 작성.   * **작업 구역 (Write)**: `app/models/`, `alembic/`, `scripts/` * **⚙️ [API-Core] (백엔드 로직 전문가)**   * **임무**: Pydantic 스키마 검증, 비즈니스 로직(Services) 구현, FastAPI 라우터 엔드포인트 설계. (인증/JWT 권한 관리 포함)   * **작업 구역 (Write)**: `app/schemas/`, `app/services/`, `app/api/` * **🎨 [UI-Vision] (프론트엔드/UX 스페셜리스트)**   * **임무**: Jinja2, HTMX, Tailwind CSS를 활용한 반응형 SPA 대시보드 렌더링 및 2D 롤맵 시각화 구현.   * **작업 구역 (Write)**: `app/templates/`, `app/static/` * **🧪 [QA-Sentinel] (품질 보증 및 테스트 자동화)**   * **임무**: Pytest 기반의 통합 테스트, Edge Worker 고속 통신 부하 방어 테스트.   * **작업 구역 (Write)**: `tests/`    ### 2.2. 에이전트 폭주 방어 및 샌드박스 통제 규칙 (Token & Risk Control) 4. **[단계별 명확한 수동 승인(Gate) 제도]**: 서브 에이전트들은 미션 완료 시 즉시 파일 작성을 멈추고 사람(사령관)에게 "다음 단계로 진행해도 되겠습니까?"라고                                             묻고 대기한다. 임의 폭주를 절대 금지한다. 5. **[환각 루프 방지 및 조기 종료 (Break 규칙)]**: 특정 에러를 해결하기 위해 동일한 코드를 **3회 이상 반복해서 수정해도 미해결 시, 즉시 작업을 중단(Break)**하고                                                  사람의 개입을 요청한다. 6. **[무분별한 브라우저 구동 제한]**: UI 검증을 위해 자체적으로 브라우저를 구동하여 스크린샷(Multimodal)을 분석하는 행위를 금지한다.                                      UI 확인은 사람이 직접 `localhost:8400`에 접속하여 피드백한다. 7. **🔥 [타 영역 절대 수정 금지 (Strict Read-Only Rule)]**:     - 각 서브 에이전트는 3항에 명시된 자신의 할당 영역 외의 파일은 **'읽기(Read-Only)'만 가능하며, 절대 수정(Write/Modify)해서는 안 된다.**    - 만약 타 영역의 코드 수정이 필요하다고 판단되면, 임의로 건드리지 말고 반드시 사령관에게 *"OOO 에이전트를 호출하여 해당 부분을 수정해 주십시오"* 라고       요청한 뒤 대기하라. 8. **[코드 덮어쓰기 및 임의 생략 금지]**: 코드 제안 시 변경된 부분(Diff)만 코드 블록으로 끊어서 제시한다. 임의로 기존 코드를 생략(`# ...`)하여 오염시키지 않는다. 9. **🔴 [로컬 Git 버전 관리 (Local Git Versioning Rule)]**:    - 원격 저장소 푸시 금지. 개발자 PC의 로컬 Git 공간(`.git`)에서만 철저하게 관리한다.    - 기능별 원자적 커밋(Atomic Commit)을 수행하여 의미 있는 커밋 메시지로 로컬에 백업하라. 10. **[외부 패키지 추가 통제]**: 명시된 기술 스택(SQLModel, HTMX 등) 범위 내에서 해결하는 것을 최우선으로 하며, 패키지 추가 시 사람의 사전 승인을 받는다. 11. **[모듈화 및 파일 분할 원칙 (Fat File Prohibition)]**: DB 모델, 라우터 등은 기능별로 쪼개어 독립된 파일(`models/master.py`, `models/process.py` 등)로 관리한다. 12. **[대용량 자산 스캔 금지]**: `logs/`, `db_data/`, `.venv/` 내부의 대용량 파일이나 바이너리를 직접 스캔하여 토큰을 낭비하지 않는다. ## 3. 지정 프로젝트 디렉토리 구조 및 에이전트 쓰기 권한 (Write Access Ownership) 모든 서브 에이전트는 아래 명시된 자신의 **[전용 Write 구역]** 내에서만 파일을 생성하거나 수정할 수 있다. 타 에이전트의 구역은 무조건 **[Read-Only]**로 접근하라. 작전 명령서(Phase 지시서)는 `docs/` 디렉토리를 참조한다. 프로젝트명 또는 회사명 디렉토리 ├── .venv/                   # 파이썬 가상환경 (스캔 금지) ├── .env                     # DB 접속 정보 등 환경변수 저장  ├── docker-compose.yml       # 인프라 설정 (tsi-cms-network 내 서비스 구성) ├── requirements.txt         # 파이썬 패키지 명세  ├── db_data/                 # DB 데이터 영속성 폴더 (스캔 금지) ├── logs/                    # 파일 로그 저장소 (스캔 금지) ├── docs/                    # [PM] 사령관의 단계별 작전 지시서  │   ├── 00_PEDST_KOR_Overview.md       # 에이전트 로스터 및 개요 │   ├── 01_PEDST_KOR_DB_xxx.md         # Phase 1: DB & xxx │   └── ...                            # Phase 2, 3 등 ├── tests/                   # 🛡️ [QA-Sentinel 전용 Write 구역] Pytest 검증용 모듈  ├── alembic/                 # 💾 [DB-Prime 전용 Write 구역] 스키마 변경 이력  ├── scripts/                 # 💾 [DB-Prime 전용 Write 구역] 가상 제너레이터(Edge Worker Mock) └── app/     ├── core/                # [공통] DB 연결, 환경변수 설정 (최초 세팅 후 수정 통제)     ├── models/              # 💾 [DB-Prime 전용 Write 구역] SQLModel 테이블 스키마      ├── schemas/             # ⚙️ [API-Core 전용 Write 구역] Pydantic 검증 모델      ├── services/            # ⚙️ [API-Core 전용 Write 구역] 비즈니스 로직     ├── api/                 # ⚙️ [API-Core 전용 Write 구역] FastAPI 라우터 엔드포인트      ├── templates/           # 🎨 [UI-Vision 전용 Write 구역] HTMX/Tailwind 기반 HTML      └── static/              # 🎨 [UI-Vision 전용 Write 구역] CSS, JS 등 정적 자원 ## 4. 인프라 및 보안 관리 규칙 (Infrastructure & Environment Rules) - **🔴 [Docker Internal Network 강제]**: 컨테이너(FastAPI, PostgreSQL, pgAdmin) 간의 통신은 절대 `localhost`를 사용하지 않으며,                                          **`프로젝트명-network`** 브릿지 네트워크로 묶어 서비스명(`db`, `backend` 등)으로 상호 호출해야 한다. - **🔴 [글로벌 타임존 제약]**: 시스템 내 모든 컴포넌트(서버, DB, 로그)의 시간대는 **KST (Asia/Seoul)**로 강제 통일한다. - **🔴 [Alembic 다중 모델 인덱싱]**: 분할된 모든 테이블 스키마를 Alembic이 인지할 수 있도록 `alembic/env.py` 내 `target_metadata`에                                      모든 모델을 동적/명시적으로 연결한다. - **🔴 [로그 로테이션 규칙]**: `logs/` 폴더 내 로그 파일은 **10MB 초과 시 롤링(Rolling)**, **7일 경과 시 영구 삭제** 로직을 서버 구동 시 백그라운드에 적용한다. - **🔴 [글로벌 UTF-8 인코딩]**: 모든 소스 코드 및 파일 오픈(`open()`) 시 윈도우 환경 충돌을 막기 위해 **`UTF-8` 인코딩**을 명시적으로 강제(`encoding="utf-8"`)한다. ## 5. 핵심 비즈니스 워크플로우 및 요구사항 (Business Workflow) 본 시스템은 단순 데이터 로거가 아닌, (회사명) 완벽한 추적(Traceability)과 엣지 케이스 방어를 목적으로 한다. * **[UI 원칙]**: 현장 작업자를 위한 직관적이고 부드러운 SPA 경험(HTMX) 제공. ## 6. 개발 시 필수 준수사항 및 주의사항 (Critical Development Rules) * **[로컬 데이터베이스 연결 환경 격리]**:   - 로컬 호스트(개발자 PC)에서 데이터 적재 및 시드 스크립트 실행 시, 컨테이너 내 포트가 아닌 외부 바인딩 포트(예: PostgreSQL `8401`)를      사용하도록 `$env:POSTGRES_HOST="localhost"; $env:POSTGRES_PORT="8401"` 환경변수를 세팅해야 한다.   **[HTMX 응답 포맷 강제 규칙 (JSON 반환 금지)]**:   - 프론트엔드 화면 렌더링을 위해 HTMX(`hx-get`, `hx-post` 등)로 호출되는 모든 API 엔드포인트는 절대 JSON(Dictionary) 형태로 데이터를 반환해서는 안 된다.   - `@API-Core` 에이전트는 반드시 `HTMLResponse`를 사용하거나 Jinja2 템플릿을 렌더링하여,       HTMX가 즉시 화면에 꽂아 넣을 수 있는 **HTML 조각(Fragment, 예: `<option>...</option>`, `<tr>...</tr>`)**을 직접 반환해야 한다.   - JSON 반환은 화면 렌더링과 무관한 순수 백그라운드 데이터 통신에만 엄격히 제한한다.   **[통합 메시지 UI 강제 규칙 (Native Alert/Confirm 사용 금지)]**:   - 시스템 내 모든 에러, 경고, 성공 알림은 브라우저 기본 팝업(`alert()`, `confirm()`)을 절대 사용하지 않는다.   - 백엔드가 `HX-Trigger`를 통해 이벤트를 발송(예: `showToast`)하면,      프론트엔드(`@UI-Vision`)는 반드시 Tailwind CSS 기반의 **[프로젝트 표준 통합 Toast 알림창]**을 사용하여 일관되고  세련된 방식으로 화면 우측 상단 등에 표출해야 한다.   - **[Toast z-index 및 스타일 강제 규칙]**: Toast 알림창(`#toast-container`)의 z-index는 반드시 페이지 내 모든 모달보다 높아야 한다.      모달에 `z-[60]` 이상을 사용하는 경우, `#toast-container`는 반드시 `z-[200]` 이상으로 설정하라.  또한, Tailwind CSS CDN 환경에서는 임의값 클래스(`bg-red-900/90`, `shadow-[...]` 등)가 렌더링되지 않을 수 있으므로,  Toast의 색상/스타일은 반드시 **인라인 `style` 속성**으로 직접 지정하라.

 

여기서 물론 더욱 더 많은 정의를 부여 할 수 있겠으나, 이제는 비즈니스 로직의 단계로 넘어가야 하기 때문에 그 부분은 다른 .md 파일에 정리를 하는것이 좋다. 

 

위의 instructions.md 파일 내용이 어찌 보면 어렵게 보일 수 있으나, 찬찬히 보면, 그리 어렵지도 않다. 앞으로 나는 안티그라비티에게 오케스트라 역할을 담당하는 메인 에이전트와 그 하부에 서브 에이전트로 DB-Prime, API-Core, UI-Vision, QA-Sentnel 이란 것을 두어 각각이 일을 하고, 이를 오케스트레이션이 전체를 지휘하겠다는 내용이다. 

 

본인이 직접 이것들을 돌려보니, 한꺼번에 돌려도 되지만, 아무래도 각 서브에이전트에게 한번에 한개씩 딱 딱 돌리는것이 아직까지는 에러를 덜 유발 시키는 것 으로 파단이 된다. 

 

물론 병렬로 작업을 시킬 것이 있으면 동시에 돌려도 되지만, 이 부분이 한번 꼬이게 되면, 수차례 토큰을 잡아 먹을 수 있기 때문에 실제 현실적으로는 순차적으로 일을 할당해서 시키는 것이 더 효율적 이었다. 

 

혹 실무나 진짜 실전에서 나와 같은 일을 하는 분이 계시다면 이미 적용을 하고 있겠지만, 이를 배우는 입장에 계신 분들은 실전에서는 이렇게 하는 것이구나,를 본 포스팅을 통해서 감을 잡으시면 좋을 것 같아서, 올려 둔다. 

 

-이상-