# [특허 기술문서 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은:

1. **CLAUDE.md에 권한 수준을 명문화**: AI가 스스로 권한을 판단
2. **사고 경험 기반 설계**: 실제 장애 사례에서 도출된 규칙
3. **단계별 에스컬레이션**: L1→자율, L2→승인, L3→거부의 자연스러운 단계
4. **코드가 아닌 자연어로 정의**: 하드코딩된 블랙리스트가 아닌, 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
