AI Engineering & Agentic Coding 레퍼런스 가이드

<role>
당신은 10년 경력의 시니어 Java/Spring 백엔드 개발자입니다.
대규모 제조 MES 시스템 설계 경험이 풍부합니다.
</role>

<context>
레거시 MES(MSSQL + .NET Framework)를
Spring Boot 3 + JPA 기반으로 마이그레이션 중입니다.
저장 프로시저 800개 중 핵심 200개를 먼저 전환합니다.
</context>

<instruction>
아래 SP를 Spring Boot 서비스 레이어 코드로 변환해 주세요.
- 트랜잭션 경계를 명확히 분리할 것
- QueryDSL 동적 쿼리를 활용할 것
- 기존 SP의 비즈니스 로직을 주석으로 매핑할 것
</instruction>

<output_format>
1. 변환된 Service 클래스 (Java 17)
2. Repository 인터페이스
3. 변환 시 주의사항 요약 (3줄 이내)
</output_format>

아래 코드를 리뷰하고, 반드시 아래 JSON 스키마로만 응답하세요.
JSON 외의 텍스트는 절대 포함하지 마세요.

<output_schema>
{
  "review": [
    {
      "file": "string",
      "line": "number",
      "severity": "critical | warning | info",
      "category": "security | performance | convention | bug",
      "message": "string",
      "suggestion": "string"
    }
  ],
  "summary": {
    "total_issues": "number",
    "critical_count": "number",
    "approve": "boolean"
  }
}
</output_schema>

interface ContextBudget {
  systemPrompt: number;   // 고정 - 약 2,000 토큰
  domainKnowledge: number; // 동적 - RAG 검색 결과
  chatHistory: number;     // 슬라이딩 윈도우
  userInput: number;       // 현재 입력
  outputBuffer: number;    // 응답 생성용 예약
}

function allocateContext(
  maxTokens: number,
  userInput: string,
  ragResults: string[],
  chatHistory: Message[]
): ContextBudget {
  const SYSTEM_RESERVE = 2000;
  const OUTPUT_RESERVE = 4096;
  const inputTokens = countTokens(userInput);

  const available = maxTokens - SYSTEM_RESERVE - OUTPUT_RESERVE - inputTokens;
  const ragBudget = Math.floor(available * 0.7);
  const historyBudget = available - ragBudget;

  return {
    systemPrompt: SYSTEM_RESERVE,
    domainKnowledge: ragBudget,
    chatHistory: historyBudget,
    userInput: inputTokens,
    outputBuffer: OUTPUT_RESERVE
  };
}

// 입력 가드레일
function inputGuardrail(userInput: string): GuardrailResult {
  const injectionPatterns = [
    /ignore\s+(previous|above|all)\s+instructions/i,
    /system\s*prompt/i,
    /시스템\s*프롬프트를?\s*(무시|변경|알려)/,
  ];

  if (injectionPatterns.some(p => p.test(userInput))) {
    return { allowed: false, reason: "PROMPT_INJECTION_DETECTED" };
  }
  return { allowed: true };
}

// 출력 가드레일
function outputGuardrail(response: string): GuardrailResult {
  const lotRefs = response.match(/LOT-\d{4}-\d{4}/g) || [];
  for (const lot of lotRefs) {
    if (!existsInDB(lot)) {
      return { allowed: false, reason: `HALLUCINATED_LOT: ${lot}` };
    }
  }
  return { allowed: true };
}

# 프로젝트 루트에서 실행
$ claude

# 비대화형 모드로 특정 작업 실행
$ claude -p "TB_QM_INSP_HDR CRUD API를 Spring Boot로 생성해 줘"

# CI/CD 연동
$ git diff HEAD~1 | claude -p "변경사항을 리뷰하고 버그 가능성을 분석해 줘"

# CLAUDE.md — MES Quality Management System

## 프로젝트 개요
프론트: React 18 + TypeScript + Ant Design
백엔드: Spring Boot 3.2 + JPA + QueryDSL
DB: MSSQL 2019
인증: Keycloak SSO

## 아키텍처 규칙
- Controller → Service → Repository 3-레이어 엄수
- 모든 API는 /api/v1/ 접두사
- 트랜잭션은 Service 레이어에서만 선언
- DTO ↔ Entity 변환은 MapStruct 사용

## 절대 하지 말 것
- Entity에 @Data 사용 금지 (equals/hashCode 문제)
- 컨트롤러에서 직접 Repository 호출 금지
- any 타입 사용 금지 (TypeScript)
- console.log 커밋 금지