24e31e0ae6
- 문서1: 온보딩 자동화 5단계 흐름도 + 필수 구성 요소 + 청구항 초안 - 문서2: As-Is/To-Be 수치 대조표 (7개 영역 비교, 비용 절감 효과) - 문서3: AI 프롬프트 엔지니어링 4계층 아키텍처 + 도메인 지식 베이스
26 KiB
26 KiB
[특허 기술문서 3] SAM 프롬프트 엔지니어링 아키텍처 — 핵심 골격
문서 목적: 변리사 제출용 — AI 프롬프팅 엔진의 설계된 로직(Engineered Logic) 입증 핵심 주장: 단순 프롬프트가 아닌, 다계층 구조화된 도메인 지식 주입 + 알고리즘 자동화 엔진 작성일: 2026-03-20 출원인: (주)코드브릿지엑스
1. 개요 — 왜 "프롬프트 엔지니어링"이 특허 대상인가
1.1 일반적인 AI 프롬프트 vs SAM의 프롬프트 엔진
일반적인 AI 프롬프트:
┌────────────────────────┐
│ "이 코드를 수정해줘" │ ← 단일 텍스트 지시
│ (1줄 ~ 수십줄) │
└────────────────────────┘
SAM의 프롬프트 엔지니어링 아키텍처:
┌──────────────────────────────────────────────────────────┐
│ 계층 1: 전역 규칙 CLAUDE.md │
│ ├── 계층 2: 프로젝트 규칙 CLAUDE.md │
│ │ ├── 계층 3: 서비스별 규칙 CLAUDE.md (mng/api) │
│ │ │ ├── 45개 Skills (도메인 특화 명령 체계) │
│ │ │ ├── 12개 Agents (전문 분야별 AI 에이전트) │
│ │ │ └── 20만줄+ 도메인 문서 (비즈니스 지식 베이스) │
│ │ │ │
│ │ └── 조건부 트리거 시스템 │
│ │ "개발서버 푸시" → 3개 저장소 자동 배포 │
│ │ "운영서버 푸시" → cherry-pick 선택적 배포 │
│ │ "이관" → 4가지 이관 워크플로우 메뉴 │
│ │ │
│ └── 3단계 서버 접근 권한 제어 (L1/L2/L3) │
│ L1(읽기): 자율 허용 │
│ L2(변경): 사용자 승인 필수 │
│ L3(위험): AI 실행 절대 금지 │
└──────────────────────────────────────────────────────────┘
규모: 4개 CLAUDE.md (합산 3,000줄+) + 45 Skills + 12 Agents + 20만줄 문서
1.2 핵심 차별점
| 요소 | 일반 AI 사용 | SAM 프롬프트 엔진 |
|---|---|---|
| 프롬프트 구조 | 단일 텍스트 | 4계층 범위별 상속 |
| 지식 베이스 | 없음 / 수동 제공 | 20만줄 자동 참조 |
| 실행 자동화 | 없음 | 자연어 트리거 → 복잡 절차 자동 실행 |
| 안전 제어 | 없음 | L1/L2/L3 3단계 권한 |
| 전문화 | 범용 | 45개 도메인 스킬 + 12개 전문 에이전트 |
| 코드 생성 품질 | 일반적 | 267모델 멀티테넌트 규칙 자동 적용 |
2. 4계층 프롬프트 아키텍처 — 상세 구조
2.1 계층 구조와 범위
┌─────────────────────────────────────────────────────────────────┐
│ 계층 1: 전역 규칙 (/home/aweso/CLAUDE.md) │
│ ───────────────────────────────────────── │
│ 적용 범위: 이 사용자의 모든 프로젝트 │
│ │
│ 포함 내용: │
│ • SAM 프로젝트 개요 + 참조 경로 │
│ • Git 커밋 규칙 (type: [scope] 한글 메시지) │
│ • 푸시 정책 (개발서버/운영서버 트리거) │
│ • Bearer 토큰 + 멀티테넌시 인증 필수 규칙 │
│ • 화이트리스트 자동 감지 트리거 │
│ • PDF 폰트 정책, React 빌드 정책 │
│ • DB 아키텍처 (마이그레이션 소유 기준) │
│ • 메뉴 관리 규칙 (시더 실행 절대 금지) │
│ • 3단계 서버 접근 정책 (L1/L2/L3) │
│ • 문서 작성 규칙, PPT 제작 규칙 │
│ │
│ 규모: ~800줄 │
├─────────────────────────────────────────────────────────────────┤
│ 계층 2: SAM 루트 규칙 (/home/aweso/sam/CLAUDE.md) │
│ ───────────────────────────────────────── │
│ 적용 범위: sam/ 하위 3개 독립 저장소 전체 │
│ │
│ 포함 내용: │
│ • MNG 자동 푸시 정책 (커밋 즉시 develop+main 배포) │
│ • 실행 환경 3-Tier 비교 (로컬Docker/개발서버/운영서버) │
│ • 도메인 매핑 표 (dev.sam.kr, admin.codebridge-x.com 등) │
│ • 공동 개발 워크플로우 (브랜치 전략, pull 후 체크리스트) │
│ • 에이전트 목록 (12개) + 스킬 목록 (45개) │
│ │
│ 규모: ~1,085줄 │
├─────────────────────────────────────────────────────────────────┤
│ 계층 3: 서비스별 규칙 │
│ ───────────────────────────────────────── │
│ │
│ MNG (/home/aweso/sam/mng/CLAUDE.md): │
│ • 기술 스택: Laravel 12 + PHP 8.4 + HTMX + Tailwind 4.0 │
│ • Tailwind 레이아웃 규칙 (min-h-screen 금지 등) │
│ • HTMX 사용 규칙 (SSR 기반 동적 UI) │
│ • MNG 전용 Blade 컴포넌트 목록 │
│ • DB 환경 (sam-mysql-1 → 114.203.209.83:3306) │
│ 규모: ~350줄 │
│ │
│ API (/home/aweso/sam/api/CLAUDE.md): │
│ • Laravel 12 REST API 규칙 │
│ • Service-First 아키텍처 강제 │
│ • FormRequest 검증 규칙 │
│ • Sanctum 토큰 인증 규칙 │
│ 규모: ~300줄 │
├─────────────────────────────────────────────────────────────────┤
│ 계층 4: docs 규칙 (/home/aweso/sam/docs/CLAUDE.md) │
│ ───────────────────────────────────────── │
│ 적용 범위: 문서 저장소 전용 │
│ 포함 내용: 계층 2와 동일 (docs는 sam 루트 규칙 공유) │
└─────────────────────────────────────────────────────────────────┘
2.2 계층간 상속과 오버라이드 메커니즘
Claude Code가 /home/aweso/sam/mng/ 에서 작업할 때 로드되는 규칙:
① /home/aweso/CLAUDE.md ← 전역 규칙 (항상 로드)
② /home/aweso/sam/CLAUDE.md ← SAM 공통 규칙
③ /home/aweso/sam/mng/CLAUDE.md ← MNG 전용 규칙
→ 3개 파일이 순서대로 적용되어 합산 2,200줄+ 의 규칙이 AI 컨텍스트에 주입
충돌 시: 하위 계층이 상위를 오버라이드
예: 전역에서 "푸시는 사용자 요청 시만" → MNG에서 "커밋 즉시 자동 푸시"로 오버라이드
3. 자연어 트리거 기반 자동화 시스템
3.1 트리거 목록과 실행 흐름
SAM의 CLAUDE.md에는 특정 자연어 입력 시 복잡한 절차가 자동 실행되는 8개의 트리거가 정의되어 있다:
| 트리거 워드 | 실행되는 자동화 절차 | 복잡도 |
|---|---|---|
"개발서버 푸시" |
3개 저장소 status → 커밋 → push develop | 12단계 |
"운영서버 푸시" |
develop push → 커밋 목록 표시 → 승인 → cherry-pick → main push | 10단계 |
"이관" |
4가지 이관 메뉴 표시 → 번호 선택 → 워크플로우 실행 | 가변 |
"sam설명" |
특정 문서 읽기 → 전체 도메인 컨텍스트 파악 | 3단계 |
| MNG 코드 커밋 시 | 자동으로 develop+main 양쪽 push | 5단계 |
| API 호출 코드 작성 시 | 화이트리스트 확인 → 없으면 추가 안내 | 3단계 |
| 401/400 오류 감지 시 | 토큰 누락 → 만료 → 화이트리스트 순서 자동 진단 | 3단계 |
| React API 연동 시 | authenticatedFetch 사용 확인 (직접 fetch 금지) | 2단계 |
3.2 운영서버 푸시 — 가장 복잡한 트리거 (상세)
사용자: "운영서버 푸시"
│
├─ [1] 각 프로젝트(api, mng)에서 develop 미푸시 커밋 확인
│ → 있으면 먼저 git push origin develop
│
├─ [2] 이번 세션 커밋 해시 목록을 git log --oneline으로 추출
│
├─ [3] 사용자에게 cherry-pick 대상 목록 표시
│ → 사용자 "확인" 응답 대기
│
├─ [4] git checkout main
│
├─ [5] git pull origin main (최신화 — 충돌 방지 핵심)
│
├─ [6] git cherry-pick <commit1> <commit2> ...
│ → 시간순 (오래된 것부터)
│ → 충돌 발생 시 사용자에게 알리고 해결 지원
│
├─ [7] git push origin main → Jenkins 자동 배포
│
├─ [8] git checkout develop (복귀)
│
└─ [9] 결과 요약 (체리픽한 커밋 목록 포함)
핵심 혁신: git merge develop(전체 머지)이 아닌 cherry-pick(선택적 반영)
→ 다른 개발자의 미검증 커밋이 운영에 올라가는 것을 AI 수준에서 차단
→ 이 "선택적 운영 배포" 로직이 자연어 한마디로 실행됨
4. 도메인 지식 베이스 — 20만줄+ 구조화된 문서
4.1 문서 카테고리별 규모
sam/docs/
├── features/ 기능별 심층 문서
│ ├── ai/ AI 리포트, 토큰 관리
│ ├── quotes/ 견적 시스템, BOM 10단계
│ ├── quality-management/ 품질관리, 건기원
│ ├── finance/ 급여, 회계, 전표
│ ├── barobill/ 바로빌 SOAP 연동
│ ├── sales/ 영업, 인터뷰, 재고생산
│ ├── equipment/ 설비 점검
│ ├── esign/ 전자서명
│ ├── email/ 이메일 발송
│ └── credit-evaluation/ 신용평가
│
├── rules/ 비즈니스 규칙
│ ├── pricing-policy.md 6 Depth 단가 체계
│ ├── numbering-rules.md 패턴 기반 채번
│ ├── item-policy.md 품목 정책
│ ├── billing-policy.md 3단계 과금
│ └── wip-production-policy.md 재공품 정책
│
├── standards/ 코딩 컨벤션
│ ├── options-column-policy.md JSON 컬럼 정책
│ ├── git-conventions.md Git 규칙
│ └── pdf-font-policy.md PDF 폰트 정책
│
├── system/ 시스템 아키텍처
│ ├── security-policy.md 5계층 보안
│ ├── database/ DB 스키마
│ └── overview.md 아키텍처 설계
│
├── dev/ 개발 가이드
│ ├── standards/ API 규칙, 품질 체크리스트
│ ├── guides/ 구현 매뉴얼
│ └── dev_plans/ 개발 계획
│
├── plans/ 임시 계획 (완료 후 삭제)
└── changes/ 변경 이력
4.2 AI가 문서를 활용하는 방식
[코드 작성 요청]
↓
Claude Code가 CLAUDE.md의 지시에 따라 관련 문서 탐색
↓
예: "견적 API 수정" 요청 시:
① CLAUDE.md "견적관리" → docs/features/quotes/README.md 읽기
② CLAUDE.md "API 개발" → docs/dev/standards/api-rules.md 읽기
③ CLAUDE.md "단가관리" → docs/rules/pricing-policy.md 읽기
④ CLAUDE.md "보안" → docs/system/security-policy.md 읽기
↓
4개 문서의 비즈니스 규칙 + 코딩 표준이 AI 컨텍스트에 주입
↓
코드 생성 시 자동 적용:
• Service-First 패턴
• FormRequest 검증
• BelongsToTenant 적용
• 3단계 단가 우선순위 준수
• options JSON 정책 준수
5. 45개 Skills — 도메인 특화 명령 체계
5.1 아키텍처
사용자 → "/code-quality-checker" 입력
↓
Claude Code가 ~/.claude/skills/code-quality-checker/ 의 정의 파일 로드
↓
스킬 정의에 포함된:
• 역할 정의 (전문가 페르소나)
• 분석 기준 (DRY/KISS/YAGNI/아키텍처)
• 출력 형식 (SEC-/PERF-/MNT-/ARCH- 접두사)
• 사용 도구 (Read, Grep, Glob, Bash 등)
↓
AI가 해당 전문가로서 코드 분석 실행
↓
구조화된 리포트 출력
5.2 4개 출처 통합
| 출처 | 스킬 수 | 특징 | 예시 |
|---|---|---|---|
| Anthropic 공식 | 2개 | 범용 고품질 | frontend-design, webapp-testing |
| Trail of Bits | 5개 | 보안 전문 | static-analysis, insecure-defaults |
| levnikolaevich | 16개 | 코드 품질 감사 | code-quality-auditor, dead-code-auditor |
| SAM 자체 제작 | 22개+ | 프로젝트 특화 | sam-docs-writer, pptx-skill, 웹문서 |
5.3 SAM 전용 스킬 — 독창성
sam-docs-writer: 문서 작성 시 역할 기반 폴더 라우팅 + 템플릿 자동 적용 + INDEX.md 자동 등록. SAM의 문서 거버넌스를 AI가 자동으로 준수하게 강제하는 스킬.
pptx-skill: HTML 슬라이드 → PowerPoint 변환. (주)코드브릿지엑스 BI 로고 + 푸터 규칙을 자동 적용.
웹문서: SAM 프로젝트의 PHP/HTML 웹문서 생성 시 디자인 표준을 자동 적용.
6. 12개 Agents — 전문 분야별 AI 에이전트 계층
6.1 에이전트 계층 아키텍처
┌─────────────────────────────────────────────────────────┐
│ 사용자 요청 │
│ ↓ │
│ 메인 Claude Code │
│ ↓ │
│ ┌─────────── 에이전트 디스패치 ──────────┐ │
│ │ │ │
│ ▼ ▼ ▼ │
│ laravel-expert code-reviewer security-auditor │
│ │ │ │ │
│ ├─ SAM Docker ├─ 메모리 학습 ├─ OWASP 10 │
│ ├─ 멀티테넌트 ├─ 패턴 누적 ├─ 취약점 탐지 │
│ └─ 마이그레이션 └─ 체크리스트 └─ 수정 제안 │
│ │ │ │
│ └── /code-quality-checker (스킬 호출) ──┘ │
│ │
│ 에이전트가 스킬을 호출하는 2단계 계층 구조 │
└─────────────────────────────────────────────────────────┘
6.2 laravel-expert — SAM 도메인 인지 에이전트
이 에이전트는 일반 Laravel 지식에 더해 SAM의 특수 환경을 사전 인지:
- Docker 컨테이너 명령 패턴:
docker exec sam-api-1 php artisan ... - 마이그레이션은 API에서만 실행하는 규칙
- 멀티테넌트 Global Scope 검증
- options JSON 컬럼 정책 자동 적용
- FormRequest + Service-First 패턴 강제
7. 3단계 AI 안전 제어 — 서버 접근 권한 시스템
7.1 설계 배경
2026-02-21 실제 사고: Claude가 SSH로 서버에 접속하여 설정 파일을 변경 → 502 Bad Gateway 발생 → AI 자율성의 위험을 경험
7.2 3단계 아키텍처
┌──────────────────────────────────────────────────┐
│ 🟢 L1 (읽기 전용) — AI 자율 실행 허용 │
│ │
│ ls, cat, head, tail 파일/디렉토리 조회 │
│ ps aux, top, htop 프로세스 확인 │
│ git status, git log Git 상태 조회 │
│ tail -f *.log 로그 실시간 조회 │
│ systemctl status 서비스 상태 조회 │
│ nginx -t 설정 검증 (변경 아님) │
├──────────────────────────────────────────────────┤
│ 🟡 L2 (경미한 변경) — 사용자 승인 후 실행 │
│ │
│ 절차: AI가 명령어를 표시 → 사용자 승인 → 실행 │
│ │
│ git pull 코드 업데이트 │
│ composer install 의존성 설치 │
│ php artisan migrate DB 마이그레이션 │
│ cache:clear 캐시 초기화 │
│ systemctl restart 서비스 재시작 │
├──────────────────────────────────────────────────┤
│ 🔴 L3 (위험) — AI 절대 실행 금지 │
│ │
│ AI는 명령어를 안내만 제공, 직접 실행하지 않음 │
│ │
│ rm -rf 대량 파일 삭제 │
│ nginx 설정 수정 서비스 중단 위험 │
│ /etc/ 하위 변경 시스템 설정 위험 │
│ DB DROP/TRUNCATE 데이터 손실 위험 │
│ kill -9 프로세스 강제 종료 │
│ 서버 재부팅 전체 서비스 중단 │
└──────────────────────────────────────────────────┘
7.3 특허 관점 진보성
기존 AI 코딩 도구(GitHub Copilot, Cursor 등)는 서버 접근 권한 제어가 없다. SAM은:
- CLAUDE.md에 권한 수준을 명문화: AI가 스스로 권한을 판단
- 사고 경험 기반 설계: 실제 장애 사례에서 도출된 규칙
- 단계별 에스컬레이션: L1→자율, L2→승인, L3→거부의 자연스러운 단계
- 코드가 아닌 자연어로 정의: 하드코딩된 블랙리스트가 아닌, AI의 판단력을 활용한 유연한 분류
8. AI 기능 구현 현황 — 코드 수준 증빙
8.1 AiReportService (구현 완료, 운영 중)
입력: tenantId, reportType, period
↓
[1] 테넌트 격리 자동 적용 ($this->tenantId())
↓
[2] 6개 도메인 데이터 자동 수집
├─ 지출 (Withdrawal)
├─ 매출 (Sale)
├─ 매입 (Purchase)
├─ 입출금 (Deposit/Withdrawal)
├─ 카드/계좌 (Card)
└─ 미수금 (Receivable)
+ 전월 동기간 동시 집계 → 증감률 자동 계산
↓
[3] 프롬프트 구성 (buildPrompt)
├─ 역할: "기업 재무 분석 전문가"
├─ 작성 규칙 6개 (숫자 형식, 구체적 명칭 등)
├─ 상태 코드 4단계 (경고/주의/긍정/양호)
├─ 분석 영역 6개
└─ 출력 JSON 스키마 명시
↓
[4] Gemini API 호출 (responseMimeType: 'application/json')
↓
[5] 토큰 비용 자동 추적
usageMetadata → 입력/출력 토큰 수
× DB 단가 (AiPricingConfig)
× 환율 (getExchangeRate)
→ ai_token_usages 테이블 기록 (USD + KRW)
↓
[6] ai_reports 테이블 저장
증빙: api/app/Services/AiReportService.php (475줄)
8.2 AI 견적서 자동생성 엔진 (설계 완료, 구현 예정)
입력: 인터뷰 텍스트 + 회사정보
↓
[1차 LLM 호출] 업무 도메인 분석
입력: 고객 인터뷰 + 회사정보
출력: {company_analysis, business_domains, recommendations}
↓
[모듈 카탈로그 매핑]
ai_quotation_modules 테이블 ↔ 분석 결과 자동 매칭
↓
[2차 LLM 호출] 견적서 생성
입력: 1차 결과 + 요금 정책 + 모듈 카탈로그
출력: {quotation.items[], summary, implementation_plan}
↓
quotes 테이블 저장 (status: draft) → 매니저 검토
증빙: docs/plans/ai-quotation-engine-plan.md (929줄)
8.3 음성 → STT → AI 분석 파이프라인 (구현 완료)
브라우저 녹음 → Web Speech API (실시간 STT, 무료)
→ Google Cloud STT (화자 분리, 유료)
↓
GCS 저장 → STT 변환 → Gemini 분석
↓
회의록 자동 생성 (MeetingMinuteService)
지원 공급자:
├─ Gemini: 입력/출력 토큰당 과금
├─ Claude: 입력/출력 토큰당 과금
├─ Google STT: 15초당 $0.009
├─ Google GCS: 1000건당 $0.005
└─ Cloudflare R2: 1M건당 $0.0045
모든 비용이 ai_token_usages 테이블에 자동 기록
→ 테넌트별 AI 비용 투명화
9. 선행기술 대비 독창성 — 종합
| 구분 | 기존 AI 코딩 도구 | 기존 SaaS ERP | SAM 프롬프트 엔진 |
|---|---|---|---|
| AI 역할 | 코드 자동완성 | 없음 | 시스템 구축 자동화 |
| 프롬프트 구조 | 단일 시스템 프롬프트 | — | 4계층 범위별 상속 |
| 도메인 지식 | 일반 코딩 지식 | — | 20만줄 산업 특화 |
| 안전 제어 | 없음 | — | L1/L2/L3 3단계 |
| 배포 자동화 | 없음 | CI/CD | 자연어 → cherry-pick |
| 에이전트 계층 | 없음 | — | 12 에이전트 × 45 스킬 |
| 비용 투명화 | 없음 | — | 4 공급자 자동 추적 |
| 멀티테넌트 인지 | ❌ | △ | 267모델 자동 격리 |
9.1 특허 축1 (플랫폼 방법특허) 기여
프롬프트 엔진이 플랫폼 방법특허의 핵심 기술:
[고객 인터뷰 데이터]
↓
[20만줄 도메인 지식 + 프롬프트 4계층]
↓ ← 이 부분이 프롬프트 엔진
[LLM 분석 (업종·규모·공정 패턴 도출)]
↓
[TenantBootstrapper + 동적 필드 + Zero-Config]
↓
[맞춤형 ERP/MES 자동 구성]
없으면 성립하지 않는 필수 구성 요소:
- 4계층 프롬프트 없이는 AI가 SAM의 비즈니스 규칙을 모름
- 20만줄 문서 없이는 업종 특화 패턴 도출 불가
- L1/L2/L3 없이는 AI 자동화의 안전성 보장 불가
10. 증빙 파일 목록
| 증빙 | 경로 | 규모 | 내용 |
|---|---|---|---|
| 전역 CLAUDE.md | /home/aweso/CLAUDE.md |
~800줄 | 전역 규칙 + 트리거 |
| SAM CLAUDE.md | /home/aweso/sam/CLAUDE.md |
~1,085줄 | SAM 공통 + 에이전트/스킬 |
| MNG CLAUDE.md | /home/aweso/sam/mng/CLAUDE.md |
~350줄 | MNG 전용 규칙 |
| API CLAUDE.md | /home/aweso/sam/api/CLAUDE.md |
~300줄 | API 전용 규칙 |
| AI 리포트 서비스 | api/app/Services/AiReportService.php |
475줄 | Gemini 리포트 + 비용 추적 |
| AI 견적 엔진 설계 | docs/plans/ai-quotation-engine-plan.md |
929줄 | 2단계 LLM 파이프라인 |
| AI 기능 문서 | docs/features/ai/README.md |
— | AI 전체 기능 명세 |
| 보안 정책 | docs/system/security-policy.md |
783줄 | 5계층 보안 + 권한 |
| Skills 디렉토리 | ~/.claude/skills/ |
45개 | 도메인 특화 스킬 |
| Agents 디렉토리 | ~/.claude/agents/ |
12개 | 전문 에이전트 |
| 도메인 문서 전체 | sam/docs/ |
20만줄+ | 비즈니스 지식 베이스 |
최종 업데이트: 2026-03-20