문제 인식: 지금은 어떻게 돌아가나
호자는 이미 상당 부분 자동화되어 있습니다. 대표님은 승인과 검토만 하고, 현장 직원은 출력된 작업지시서대로 움직입니다. 그 사이를 봇 10개(김부장·김출고·김재고·김쿠팡·김발주·김고객·김리뷰·김보고·김계산·김정리)와 파이썬 exe 프로그램 13개가 메웁니다. 문제는 "자동화가 있다"가 아니라 "자동화가 한 PC와 프롬프트에 묶여 있다"는 점입니다.
원격 작업이 크롬 원격데스크톱 100% 의존
대표님은 사무실 밖에서 메신저와 원격데스크톱으로 자동화를 수정하고 작업을 지시합니다. PC가 꺼지거나 세션이 끊기면 수정도, 장애 대응도 불가능합니다. 사람이 그 PC 화면을 "빌려 쓰는" 구조라 동시에 여러 명이 일할 수 없습니다.
에이전트가 프롬프트 지침에만 의존
"김출고"는 역할 설명일 뿐 실행 절차가 강제되지 않습니다. 같은 요청에도 결과가 달라지고, 틀렸을 때 왜 틀렸는지 기록이 남지 않습니다.
사람과 에이전트가 다른 길로 일함
exe는 사람이 클릭하는 GUI입니다. 에이전트가 같은 일을 하려면 우회로를 만들어야 하고, 그 순간 "같은 업무, 다른 결과"가 생깁니다.
목표
회사 인원이 에이전트와 기능을 자유롭게, 그리고 안전하게 업데이트 최우선 · 업체 요구
대표·이사가 Claude에게 "이렇게 바꿔줘"라고 말하면 결과를 미리 확인한 뒤 적용되고, 문제가 생기면 언제든 이전 버전으로 되돌릴 수 있어야 합니다.
장소 제약 없이 어디서든 일하기
원격데스크톱으로 PC를 빌리는 대신, 서버의 기능을 웹·Telegram·Claude로 직접 호출합니다.
에이전트가 사람이 쓰는 기능을 그대로 사용
사람이 웹에서 누르는 버튼과 에이전트가 호출하는 툴이 정확히 같은 코드를 실행합니다.
개발자의 역할 (대전제)
개발자는 Docker 등 바탕 시스템을 제공합니다. 세부 업무 기능은 기존 기능을 그대로 가져오고, 그 기능을 회사가 계속 업데이트할 수 있게 만드는 것이 개발자의 일입니다. 즉 "기능을 새로 만드는 SI"가 아니라 "기능이 자라는 판을 까는 SI"입니다.
개발 방향: 여섯 가지 원칙
① 기능은 한 번만 정의한다
실무기능 하나 = 파이썬 함수 하나 + 입력/출력 스키마. 웹 화면, REST API, MCP 툴, n8n 호출은 모두 이 정의에서 자동으로 나옵니다. MCP용·사람용을 따로 만들지 않습니다.
② 에이전트는 "입과 귀", 기능은 "손"
Hermes와 봇은 대화·판단·요약만 하고, 실제 작업은 반드시 기능(툴)을 호출해서 합니다. 에이전트가 exe를 직접 실행하거나 파일을 만지는 우회로를 막습니다.
③ 반복 업무는 워크플로우로 고정한다
정해진 시각, 정해진 순서로 돌아야 하는 일(소매 08:30, 도매 14:00, 금요일 발주)은 n8n 워크플로우가 결정적으로 실행합니다. LLM은 메일 분류·리뷰 초안처럼 좁은 단계에만 쓰고 결과는 스키마로 검증합니다.
④ 모든 실행은 작업큐와 기록을 거친다
누가(사람/어느 에이전트), 무엇을, 어떤 입력으로, 결과가 어땠는지 한 테이블에 남습니다. 위험한 작업은 대표님 승인 후에만 실행됩니다.
⑤ 모든 수정은 버전으로 남는다
기능, 에이전트 역할, 워크플로우, 업무 규칙 값의 모든 변경이 자동으로 버전 저장됩니다. 웹뷰에서 언제든 이전 버전으로 되돌릴 수 있습니다.
⑥ 규칙 값은 코드 밖으로
팔레트 112cm, 신규 95%·혼합 90%, 진열 보충 10%, 각종 스케줄 시각은 YAML 설정으로 분리합니다. 대표님 요청의 대부분이 "설정 한 줄 수정"으로 끝나게 됩니다.
전체 아키텍처
서버 3종류, 역할을 명확히 나눕니다. 리눅스 상시서버가 "두뇌와 기록", 윈도우 실무서버가 "손", NAS가 "창고"입니다.
| 서버 | 돌아가는 것 | 이유 |
|---|---|---|
| Linux 상시 | Hermes(호스트), n8n·Gateway·Postgres·웹뷰·동기화·백업·모니터링(Docker) | 24시간 안정. Hermes는 호스트에서 돌며 서버 전체를 관리하고, 나머지는 Docker Compose로 배포·업데이트·롤백 일원화. 성능이 낮아도 수십 GB 규모 업무 DB엔 충분. |
| Windows 실무 | Worker 하나 (기존 13개 기능 로직 실행) | 브라우저 조작, 엑셀, 한글, 프린터는 윈도우가 필요. 무거운 GUI 작업이 멈춰도 대화·스케줄은 리눅스에서 계속 삶. |
| NAS 저장용 | 파일 (PDF, 엑셀 산출물, 스크린샷) | 이미 운영 중, RAID. DB에는 파일 경로만 저장. |
| NAS 백업용 | DB 덤프, WAL, 파일 백업 | 저장용과 분리된 백업 보관. |
Q. Hermes는 어디서 돌아야 하나 → 리눅스 상시서버 호스트 (Docker 밖)
Docker 안에 넣으면 머신 관리 권한이 막혀 제약이 많았던 경험이 있어, Hermes는 호스트에 직접 설치해 대표님과의 대화 + 리눅스 서버 전반 관리를 함께 맡깁니다. 단, 업무 기능(실무기능)은 서버 권한으로 직접 건드리지 않고 반드시 MCP를 통해 호출합니다.
| 기준 | Linux 상시서버 | Windows 실무서버 |
|---|---|---|
| 24시간 가동 | 안정적 | 재부팅·업데이트·GUI 세션에 좌우 |
| Telegram 상시 대기 | 독립적으로 유지 | 엑셀·브라우저가 멈추면 같이 멈춤 |
| "같은 기능" 원칙 | MCP로만 호출하도록 강제됨 | exe를 직접 실행하는 우회로가 생기기 쉬움 |
| 서버 관리 | 호스트에서 직접 실행 → Docker·백업·로그·디스크까지 관리 가능 | 업무 PC 관리와 섞임 |
실무기능 공용화: 사람과 에이전트가 같은 함수를
"에이전트는 MCP, 사람은 API+웹뷰" 방향은 맞습니다. 핵심은 둘을 따로 만들지 않는 것입니다. 하나의 정의에서 세 어댑터가 자동으로 생기고, 실행은 모두 같은 작업큐를 지납니다.
작업큐를 쓰는 이유
- 브라우저·엑셀·한글은 동시 실행 시 깨짐 → 자원별 직렬화
- Windows 재부팅에도 작업 유실 없음
- Windows에 인바운드 포트 불필요
승인 게이트
- 품절 컨펌, 세금계산서, 도매 신규, 규칙 변경 =
critical - 에이전트가 부르면
pending_approval→ 대표님 버튼 → 실행 - 사람이 웹에서 눌러도 같은 규칙
재고 단일 작성자
- 재고 변경은
inventory.apply_change하나만 - 다른 기능은 변경 요청만 등록
- DB 권한으로도 강제 (다른 롤은 UPDATE 불가)
에이전트 재설계: 프롬프트에서 워크플로우로
봇 이름과 Telegram 보고는 그대로 둡니다. 바뀌는 건 속입니다. "역할 설명 + 알아서 하기"에서 "정해진 단계 + 필요한 곳에만 LLM"으로 바뀝니다.
에이전트 정의 파일
agents/kim_chulgo/
├── role.md # 지금 Hermes 세션 프롬프트를 옮겨 옴 (성격·말투·보고 형식)
├── tools.yaml # 쓸 수 있는 기능 화이트리스트
└── sop.md # 업무 절차 (워크플로우의 사람용 설명)tools.yaml이 중요합니다. 김리뷰는 리뷰 관련 기능만, 김계산은 세금계산서 기능만 부를 수 있게 하면 에이전트가 엉뚱한 일을 할 여지가 구조적으로 사라집니다.
이관 순서 (위험 낮은 것부터)
| 순서 | 봇 | 성격 | 이유 |
|---|---|---|---|
| 1 | 김정리 | 메일 10분 주기 정리 | 읽기 위주, 실패해도 피해 적음 |
| 2 | 김보고 · 김부장 요약 | 12:00 / 18:00 보고 | 조회와 요약만 |
| 3 | 김리뷰 · 김고객 | 초안 생성 | 대표님 검토가 이미 있음 |
| 4 | 김쿠팡 · 김출고 · 김재고 · 김발주 | 출고·재고·발주 | 실물과 재고가 움직임, 병행 운영 후 전환 |
| 5 | 김계산 | 세금계산서 | 금전, 마지막에 승인 게이트와 함께 |
셀프서비스 업데이트: 회사가 직접 키우는 구조
가장 중요한 목표입니다. 핵심은 두 가지입니다. 말로 고칠 수 있고, 마음에 안 들면 언제든 이전 버전으로 되돌릴 수 있다. 이 두 가지가 보장되어야 대표·이사가 부담 없이 자동화를 계속 고쳐 나갈 수 있습니다.
웹뷰의 업데이트 노트 (예시 화면)
| 버전 | 언제 | 누가 | 무엇을 바꿨나 | |
|---|---|---|---|---|
| v14 현재 | 11/20 14:05 | 대표님 | 신규 팔레트 적재 높이 112cm → 115cm | |
| v13 | 11/19 10:30 | 이사님 | 김리뷰 답글 말투를 더 정중하게 변경 | 되돌리기 |
| v12 | 11/18 17:12 | 대표님 | 도매 출고 시각 14:00 → 13:30 | 되돌리기 |
| v11 | 11/18 09:41 | 대표님 | 쿠팡 작업지시서에 박스 수량 열 추가 | 되돌리기 |
각 줄을 누르면 바뀌기 전과 후를 나란히 비교해 볼 수 있습니다.
버전 관리는 뒤에서 자동으로
모든 수정은 자동으로 버전이 남습니다. 내부적으로는 개발자들이 쓰는 버전관리 도구(Git)가 돌아가지만, 사용자가 이를 배우거나 신경 쓸 필요는 없습니다.
실패하면 자동으로 이전 버전
수정 후 첫 실행에서 오류가 나면 자동으로 직전 버전으로 돌아가고 Telegram으로 알립니다. 업무가 멈춘 채로 방치되지 않습니다.
중요한 변경은 한 번 더 확인
재고, 금전(세금계산서·정산), 권한과 관련된 수정은 대표님 확인을 거쳐야만 적용됩니다. 규칙 값이나 보고 문구 같은 가벼운 수정은 바로 적용됩니다.
사내 용어집
"밀크런", "합팔", "1창고 선반" 같은 사내 용어를 미리 정의해 두어, 누가 Claude에게 말해도 같은 뜻으로 알아듣습니다.
인프라 · 보안 · 운영
사내 웹 화면(웹뷰)이 새로 생깁니다
지금은 실무기능을 쓰려면 사무실 PC에 원격으로 들어가 exe를 실행해야 합니다. 앞으로는 휴대폰이나 노트북 브라우저로 접속하는 회사 전용 웹 화면에서 같은 기능을 버튼으로 실행하고, 작업 기록과 수정 이력도 여기서 봅니다. 에이전트가 쓰는 기능과 정확히 같은 기능이 실행됩니다.
작업지시서 생성, 송장 출력, 품절 처리 등 exe에서 하던 일을 입력칸과 버튼으로. 새 기능이 추가되면 화면도 자동으로 생깁니다.
오늘 누가(사람/어느 에이전트) 무엇을 했고 결과가 어땠는지 한눈에. 실패하면 화면 캡처와 원인이 함께 보입니다.
대표님 승인이 필요한 작업(품절 컨펌, 세금계산서 등)과 수정 요청을 확인하고 승인. Telegram 버튼과 같은 기능입니다.
지난 작업 기록을 날짜·사람·에이전트·기능별로 검색. "지난주 쿠팡 작업지시서는 누가 몇 번 만들었나" 같은 질문에 바로 답할 수 있습니다.
자동화가 수정될 때마다 언제, 누가, 무엇을, 왜 바꿨는지 쉬운 말로 자동 정리됩니다. 문제가 생기면 여기서 이전 버전으로 되돌릴 수 있습니다.
접속: 별도 앱 설치 없이 회사 주소(예: hoja.latemarch.net)로 접속하고, 허용된 이메일로 로그인한 사람만 열립니다. 사람마다 권한이 따로 있습니다.
Postgres는 리눅스 상시서버
- 운영 DB는 몇 년 쌓여도 수~수십 GB, HDD로 충분
- n8n DB도 같은 Postgres에 DB만 분리
- 파일은 NAS, DB엔 경로만
- 데이터 폴더는 서버 로컬 디스크 (NAS 마운트 금지)
DB 백업
- 매일 pg_dump + WAL 아카이브 → 백업용 NAS
- 복원 절차 문서화, 다른 머신에 실제 복원 1회
- SMART 모니터링 → 이상 시 Telegram 알림
실무서버는 상시 가동 필수
- 07:00 리뷰, 08:30 소매, 10분 메일 등 대부분 실무기능 필요
- 자동로그인 + 절전 해제 + 재부팅 후 Worker 자동 시작
- Windows Update 재부팅 시각을 업무 외로 고정
Cloudflare Tunnel + Access로 원격데스크톱 대체
- 웹뷰·n8n 편집기는 회사 도메인 + 이메일 로그인(Access). 휴대폰·개인 PC 어디서든, 앱 설치 없음
- Claude(MCP)·n8n이 부르는 Gateway는 Access 서비스 토큰으로 보호 → 클라우드의 Claude도 접속 가능
- 서버는 바깥으로 터널만 열고 공유기 포트는 하나도 열지 않음. Postgres는 외부 노출 금지
- 서버 SSH·Windows 화면 점검도 Access 경유(브라우저 SSH/RDP). Tailscale은 관리자용 보조로 선택 사항
계정·비밀번호 관리 추가
- 마스터 데이터의 "계정" 정보(쿠팡·홈택스·택배 등)를 파일에서 꺼내 암호화 저장소로 (Docker secrets 또는 Vaultwarden)
- Git에는 비밀값 절대 금지, CI에서 자동 검사
- Gateway API 키는 사람·에이전트별로 따로 발급
서버 상태 알림 추가
- 서버·Worker가 멈추면 Telegram으로 즉시 알림 (Uptime Kuma 등)
- 작업 실패 시 스크린샷·로그를 웹뷰 작업 현황에 자동 첨부
이카운트는 회계 원장으로 유지
- Postgres는 운영 DB, 이카운트는 정산·회계의 기준
- 동기화 워커가 지금의 "공유 캐시"를 대체
LLM 사용량 관리 추가
- 워크플로우 안 LLM 호출은 Gateway를 통해 기록 → 봇별 월 비용 확인
- 분류·추출은 작은 모델, 대화·판단은 큰 모델로 나눠 씀
기존 exe를 기능으로 옮기는 방법
| 상황 | 방법 | 난이도 |
|---|---|---|
| 파이썬 소스 있음 | GUI 코드와 로직 분리 → 로직만 capabilities/로. 기존 exe는 당분간 병행 운영 | 낮음 |
| 소스 있지만 GUI와 강결합 | 1차: CLI 인자로 실행 가능하게 최소 수정해 subprocess 호출 → 2차: 분리 | 중간 |
| 소스 없음 (exe만) | 최후 수단으로 pywinauto로 GUI 조작 래핑. 불안정하므로 재작성 우선 | 높음 |
로드맵
"CLAUDE.md와 rules/ 분리"는 0단계부터 합니다. 처음부터 Claude가 읽기 좋게 쌓아야 4단계 셀프서비스가 자연스럽게 됩니다.
기반
Cloudflare Tunnel + Access, Git 저장소, CLAUDE.md, 13개 프로그램 인벤토리(소스 위치·입력·출력·부작용·스케줄), 리눅스 Docker Compose 골격 (Postgres·n8n·Gateway), Hermes 호스트 설치.
✓ 완료 기준: 앱 설치 없이 밖에서 웹뷰·n8n·서버에 접속 가능
파일럿: "같은 함수" 증명
Gateway + jobs 큐 + Windows Worker + 위험 낮은 기능 1개(예: 롯데송장 단건출력 또는 품절 조회)를 웹뷰·MCP·n8n 세 경로로 실행.
✓ 완료 기준: 사람이 웹에서 누른 것과 Hermes가 부른 것이 같은 job 기록으로 남음
데이터
Postgres 스키마, 마스터 데이터(물류·몰공용·계정) 이관, 계정 정보 암호화, 이카운트 동기화, 재고 단일 작성자 이식, 백업·복원 테스트.
✓ 완료 기준: 재고 변경이 DB 트랜잭션으로만 일어남
봇 → 워크플로우
위험 낮은 순으로 이관 (김정리 → 김보고 → 김리뷰·김고객 → 김쿠팡·김출고·김재고·김발주 → 김계산). Hermes 리눅스 이전, MCP 연결. 기존 봇과 병행 운영 후 전환.
✓ 완료 기준: 사무실 PC 없이도 하루 업무가 돌아감
셀프서비스
웹뷰 업데이트 노트·되돌리기, 변경 설명, 실패 시 자동 복귀, 중요 변경 확인 규칙, 대표·이사 온보딩(첫 수정을 같이 해보기), 운영 매뉴얼 인수인계.
✓ 완료 기준: 대표·이사가 개발자 없이 수정 → 확인 → 적용 → 필요하면 되돌리기까지 완료
결정 기록 · 리스크
결정 기록
리스크
| 리스크 | 영향 | 대응 |
|---|---|---|
| exe 소스가 없거나 일부만 있음 | 이관 비용 급증 | 0단계 인벤토리에서 먼저 확인, 없는 것은 재작성 계획 |
| 쿠팡·홈택스 등 사이트 화면 변경 | 브라우저 기능 중단 | 실패 시 스크린샷 + 즉시 알림, 기능별 버전 관리로 빠른 수정 |
| 전환기 이중 운영 혼선 | 재고 불일치 | 재고 쓰기는 한 시점에 한 시스템만, 전환일 명확히 |
| 비개발자의 시스템 수정으로 장애 | 업무 중단 | 적용 전 변경 설명, 실패 시 자동 복귀, 중요 변경은 대표님 확인, 웹뷰에서 언제든 이전 버전으로 되돌리기 |
| Windows GUI 세션 문제 | Worker 멈춤 | 자동로그인 세션 상주, Worker 헬스체크 → 자동 재시작 · 알림 |