AI-Optimized Development Protocol

SAM Code Development Policy

견적, 수주, 생산, 출하, 품질 등 MES 핵심 개발을 위한 표준 가이드라인 및
AI 컨텍스트 관리(기억상실증 방지) 패키지

📋 개요

이 문서는 SAM 시스템의 모든 기능 개발에 공통으로 적용되는 정책을 정의합니다.

각 기능별 개발 문서(MASTER_PLAN.md)는 이 문서를 참조합니다. 특히 AI 어시스턴트(Claude)가 세션 간의 컨텍스트를 잃지 않고, 일관된 품질의 코드를 생산하기 위한 기술적/정책적 장치를 포함하고 있습니다.

🧠 AI 컨텍스트 관리 및 기억상실증 방지

AI 기억 유지 도구 (Memory Kit)

Core 구조적 장치

  • CLAUDE.md: 프로젝트 기술 스택, 코딩 스타일, 개발 원칙 (루트 상시 배치)
  • PROGRESS.md: 현재 수행 중인 태스크, 완료 항목, 다음 단계(Next Step)
  • MASTER_PLAN.md: 특정 기능의 전체 아키텍처와 도메인 지식 기록

Skill 자동 복구 프로세스

  • 세션 시작 루틴: AI 부팅 시 PROGRESS.md 로드
  • 체크포인트 커밋: 주요 로직 변경 후 상태 업데이트 강제 지시
  • 컨텍스트 요약(Compaction): 결정 사항을 요약하여 별도 파일 기록

출처: Anthropic Claude Code Context Management Guidelines & GitHub Open Projects

외부 메모리 솔루션 제안

솔루션 기능 및 효과
MCP Model Context Protocol을 통한 장기 기억 저장
Super Claude Kit 작업 상태 추적 및 레지스트리 관리
claunch 프로젝트별 세션 관리 및 컨텍스트 로드

🚨 필수 준수 규칙

1. 테이블 정책

❌ 절대 금지

  • 새로운 테이블 임의 생성 (price_new, order_items_v2 등)
  • 기존 테이블 구조 임의 변경
  • mng에서 마이그레이션 실행

✅ 필수

  • 기존 테이블 우선 활용
  • 테이블 추가 필요 시 → 사용자 승인 필수
  • DB 마이그레이션은 api 프로젝트에서만 실행

2. 프로젝트 기술 스택

프로젝트 기술 스택 주의사항
mng Laravel 12 + Plain Blade + Tailwind ❌ Alpine.js 금지
api Laravel 12 + Swagger Multi-tenant 필수
5130 PHP + jQuery 분석 대상 (참조용)
react Next.js 15 프론트엔드 전담

3. 코드 컨벤션 (추측 금지 원칙)

🔴 핵심: 모든 코드 요소는 실제 확인 후 사용

❌ 절대 금지 - 추측/할루시네이션

  • 컬럼명 추측 (tenant.name → tenant.company_name 여부 확인)
  • 관계명 추측 (user.roles → user.userRoles 확인)
  • 메서드명 추측 (getName() → getCompanyName() 확인)
  • 테이블명 확인 (users → sam_users 여부 확인)

✅ 필수 확인 우선순위

  1. 모델 파일 (app/Models/*.php)
  2. 마이그레이션 (database/migrations/*.php)
  3. 기존 컨트롤러/서비스 사용 패턴
  4. 불확실하면 → 반드시 질문

🗄️ DB 테이블 및 설계 정책

SAM 테이블 설계 정책 (Hybrid EAV)

🔴 필수 컬럼 (Stored Directly)

  • 조인 필드 (FK: tenant_id, product_id 등)
  • 인덱싱 필드 (status, created_at 등)
  • 고빈도 쿼리 WHERE 조건 필드

🟢 가변 컬럼 (options JSON)

  • 비즈니스 속성 데이터
  • 설정/옵션 값
  • 확장 가능성 있는 필드 (검색 비대상)

⚠️ 컬럼 타입 정책 (Enum 지양)

  • ❌ 지양: DB enum 타입, PHP Enum 하드코딩
  • ✅ 권장: string/varchar + common_codes 테이블 관리
  • 💡 예외: is_* boolean 필드 (true/false 명확한 경우)
// ✅ 권장: string + 코드 테이블
$table->string('status', 20)->default('pending');
// ✅ 허용: is_* boolean
$table->boolean('is_active')->default(true);

🔄 Phase 진행 및 워크플로우

테이블 작업 프로세스

Step 1
5130 테이블 분석
↓
Step 2
SAM 테이블 매핑 문서화
↓
Step 3
컬럼 분류 (필수 🔴 / 가변 🟢)
↓
Step 4
사용자 승인 및 마이그레이션 생성

정책 충돌 해결 및 커밋

  • 최신 우선: 문서 간 충돌 시 최신 날짜 우선
  • 상위 우선: 상위 문서(CLAUDE.md) 우선
  • 롤백 포인트: 각 Phase 완료 시 Git 태그 생성
  • 커밋 메시지: 반드시 한글로 작성

🚀 Triple-Agent 협업 워크플로우

SAM 프로젝트는 Antigravity(실행), Claude Code(감리), TestSprite(검사)의 3단계 교차 검증을 통해 품질을 보증합니다.

Antigravity

The Doer
  • 설계 및 구현: 초기 마스터 플랜 수립 및 고속 코드 작성
  • UI/UX 가이드: 프리미엄 디자인 시스템(Glassmorphism) 적용
  • 컨텐츠 생성: 이미지, 텍스트 등 에셋 생성 주도

Claude Code

The Auditor
  • 인프라 및 감리: 파일 구조, 터미널 명령, Git 관리
  • 계획 검증: Antigravity의 계획을 회사 정책 기반으로 검토
  • 보안 및 권한: API 명세 및 멀티테넌트 로직 체크

TestSprite

The QA
  • E2E 브라우저 테스트: 사용자 관점의 프론트엔드 검증
  • Visual Regression: UI 깨짐 및 CSS 일치성 확인
  • 이슈 자동 수정: 발견된 버그의 자동 수정 제안 및 확인

실전 협업 프로세스 (Execution Cycle)

단계 활동 주체 참고 파일 (Artifacts)
1. 분석/설계 요구사항 분석 및 아키텍처 수립 Antigravity MASTER_PLAN.md
2. 정책 검증 회사 정책 준수 여부 및 구조적 무결성 검토 Claude Code CLAUDE.md
3. 코드 구현 검증된 계획 기반 고속 구현 (Phase별 진행) Antigravity PROGRESS.md
4. QA 명세 테스트 시나리오 및 PSD(Product Spec) 생성 Claude Code QA_SPEC.md
5. 최종 검증 브라우저 테스트 및 자동 버그 수정 TestSprite QA_REPORT.pnl

📁 핵심 참고 파일 및 템플릿

필수 관리 문서 (Single Source of Truth)

/docs/MASTER_PLAN.md : 프로젝트의 북극성. 전체 기능 설계도.
/docs/PROGRESS.md : 실시간 태스크 추적 및 컨텍스트 복구용.
/docs/QA_SPEC.md : TestSprite 전용 제품 사양서(PSD).

AI 가이드라인 파일 (Context Manager)

/CLAUDE.md : 프로젝트 고유 코딩 스타일 지침서.
/.claudecode/settings.json : Claude Code의 인프라 설정.
/.agent/workflows/ : 반복 작업 자동화 스크립트.

⚡ Quick Start: 워크플로우 즉각 적용

1단계: 세션 부팅 (Context Load)

새 대화 시작 시 AI에게 다음 명령을 전달하여 컨텍스트를 동기화합니다.

"PROGRESS.md와 CLAUDE.md를 읽고 현재 진행 중인 
프로젝트의 상태와 코딩 규칙을 파악해줘."

2단계: 계획 수립 (Antigravity)

작업 시작 전 아키텍처를 설계하고 승인을 받습니다.

"MASTER_PLAN_TEMPLATE.md를 기반으로 이번 
기능의 상세 설계안을 작성해줘."

3단계: 정책 검증 (Claude Code)

계획이 회사 정책에 부합하는지 감리를 요청합니다.

"이 설계안이 SAM DB 정책(Hybrid EAV)과 
보안 가이드라인을 준수하는지 검토해줘."

4단계: QA 실행 (TestSprite)

구현 완료 후 브라우저 기반 자동 테스트를 수행합니다.

"QA_SPEC.md를 기반으로 TestSprite를 실행하여 
시나리오별 동작과 UI를 검증해줘."

📝 변경 이력

날짜 버전 변경 내용 담당
2025-12-19 v1.0 초기 공통 정책 문서 작성 (MES 통합 가이드) Claude
2025-12-31 v1.1 AI 기억상실증 방지 전략 추가 Claude
2025-12-31 v1.2 Triple-Agent(Claude Code+Antigravity+TestSprite) 시너지 워크플로우 통합 Antigravity