🌐 English Edition available: Looking for the English version? Read PCIP Framework Guide (English Edition).
PCIP Framework 완전 해부: 제작 배경부터 설계 의도까지
핵심 3줄 요약
- 문제점: SOTA AI 코딩 도구들은 사용자의 지시가 조금만 모호해도 전체 아키텍처와 맥락을 무시한 채 파편화된 코드를 짜거나 치명적인 결함을 남기기 쉽습니다.
- 해결책: PCIP Framework는 의도 분석부터 프로젝트 아키텍처 파악, 도메인별 전문가(Parent) 매핑을 통해 체계적인 코드 작성을 유도합니다.
- 결과: 추상적인 요청도 안정적이고 일관된 프로덕션 품질로 연결하며, 외부 지식(RAG/MCP)과 연계해 신뢰도를 극대화합니다.
Part 1: 제작 배경 — 실제로 겪었던 참사와 한계
캐싱 최적화 중 발생한 실제 사고
- 나: “프로필 조회 속도가 너무 느려. 성능 최적화해줘.”
- AI: (고민 없이 Redis 캐싱 로직 추가)
- 나: “응답 속도가 눈에 띄게 빨라졌네! 바로 배포하자.”
- 일주일 뒤: “프로필을 수정해도 옛날 정보만 계속 보여요” 라는 유저 문의 폭증.
- 원인: 캐시 갱신/무효화(Cache Invalidation) 로직이 통째로 빠져 있었음.
- 결과: 유저 공지 후 수동으로 캐시를 전량 초기화하고 핫픽스 배포.
이때 깨달은 본질:
AI는 특정 함수나 기능 코드는 그럴듯하게 작성하지만, 시스템 전체의 ‘상태 변화와 맥락(Context)’을 스스로 챙기지 못합니다.
개발자가 일일이 떠먹여 줘야 했던 악순환
나: "결제 기능 만들어줘."
AI: "네! 기본 결제 폼과 요청 함수를 작성했습니다."
나: "잠깐, 결제는 보안이 핵심이잖아..."
나: "PCI-DSS 규정도 체크해야 하고..."
나: "환불 트랜잭션이랑 실패 시 롤백 처리는?"
나: "부정 결제(FDS) 방지와 감사 로깅은?"
나: "에러 핸들링과 결제사 타임아웃 처리는?"
AI: "아, 그렇다면 처음부터 구조를 다시 설계하겠습니다."
나: "..." (또 처음부터 다시?)
단순한 기능 구현 지시를 내릴 때마다 수십 가지 엣지 케이스와 보안 규정을 사람이 일일이 나열해 주어야 했고, 조금만 프롬프트가 길어져도 AI는 맥락을 잊거나 앞선 코드를 갈아엎기 일쑤였습니다.
Part 2: 뜻밖의 실마리 — 훈육 프로그램에서 얻은 설계 영감
야근 중 우연히 시청하게 된 육아/훈육 솔루션 프로그램에서 흥미로운 장면을 보게 되었습니다.
상담 사례 속의 대화
- 보호자: “아이가 하루 종일 게임만 붙잡고 있어요. 그만하라고 다그쳐도 도무지 말을 듣지 않습니다.”
- 일반적인 대응 방식:
- “게임 당장 그만해!” (일방적 지시)
- “게임기 압수야!” (강제 조치)
- “한 판만 더 하면 용돈 없어!” (단기적 압박)
- 전문가의 접근법:
- “무작정 중단시키기 전에, 아이가 게임을 통해 어떤 심리적 결핍이나 욕구를 채우려 하는지 근본 원인을 먼저 살펴야 합니다.”
- “단순한 통제가 아니라, 아이의 상황에 맞는 대안을 제시하고 장기적인 기준과 방향성을 함께 지도해야 합니다.”
순간 머리를 스치는 생각이 있었습니다.
"AI 코딩 어시스턴트에게 지시를 내릴 때도 완전히 똑같지 않은가?"
단순히 "이 기능 구현해"라고 명령하기만 하면:
- 전체 맥락 파악 (X)
- 아키텍처 관점의 위험 평가 (X)
- 보안/성능 엣지 케이스 고려 (X)
결국 AI에게도 지시를 무비판적으로 실행하기 전에,
상황을 조율하고 적절한 지침을 내려줄 '좋은 가이드(Parent/Expert)' 역할이 필요했던 것입니다.
좋은 훈육의 원리를 시스템 프롬프트로 치환하기
| 훈육의 핵심 원리 | 소프트웨어 개발(PCIP) 적용 |
|---|---|
| 1. 동기 및 상황 파악 | 요청의 복잡도와 프로젝트 맥락(Context)을 먼저 분석 |
| 2. 리스크 사전 예측 | 이 작업이 기존 시스템에 미칠 부작용(위험도 Level 1~5) 평가 |
| 3. 전체 환경 고려 | 기술 스택, 아키텍처 패턴, 비즈니스 규칙 종합 점검 |
| 4. 명확한 가이드 제시 | 단순 코드 생성이 아닌, 해당 도메인 전문가 관점의 접근법 설정 |
| 5. 지속적 피드백 | 구현 결과물이 시스템 품질 기준을 충족하는지 다단계 검증 |
Part 3: PCIP 시스템 아키텍처
기존 방식 vs PCIP 방식
- 기존 방식:
사용자 요청 → AI 즉시 생성 → 검증되지 않은 위험한 코드 산출 ("결제 모듈 짜줘" → 보안/트랜잭션 고려 없는 단순 코드) - PCIP 구조:
사용자 요청 → PM (상황 분석/위험도 산정) → Parent (도메인 전문가 가이드) → Child (정밀 실행) ("결제 모듈 짜줘" → 위험도 High 판정 → 보안/결제 전문가 투입 → 규정 준수 및 안전한 코드 작성)
Part 4: 레이어별 상세 설계 의도
4-1. 3-Layer(3계층) 구조를 선택한 이유
다양한 시행착오를 거치며 가장 안정적인 3계층 구조를 도출했습니다:
- 1계층 (단일 에이전트): 기존의 방식. 맥락 유실과 품질 편차가 심함.
- 2계층 (관리자-실행자): 관리자가 너무 많은 책임을 떠안아 특정 도메인의 디테일(보안 규정, UX 등)이 흐려짐.
- 4계층 이상: 프롬프트 토큰 소모가 극심하고 응답 속도가 현저히 저하됨.
최종 확정된 3계층 구조:
- PM (Meta): 프로젝트 전반의 의도와 위험도를 파악하는 오케스트레이터 (총괄 책임자)
- Expert (Parent): 특정 분야의 전문 지식과 가이드라인을 주입하는 멘토 (테크 리드)
- Child (Execution): 가이드에 맞춰 정확하고 간결하게 코드를 작성하는 실행자 (실무 개발자)
실제 개발 조직의 워크플로우를 그대로 모델링했기 때문에 AI가 환각을 최소화하고 제 역할을 수행합니다.
4-2. PM의 페르소나를 ‘15년 차 시니어 PM’으로 구체화한 이유
단순히 “너는 관리자야” 라고 지시하면 AI는 모호한 태도를 취합니다.
반면 “15년 경력의 시니어 프로젝트 매니저로서 대화 맥락을 분석하고 전문가를 배치하라”고 구체화하면, AI의 내부 가중치가 시스템 설계와 리스크 관리 중심으로 정렬되어 일관된 판단을 내리게 됩니다.
4-3. 위험도 5단계(Level 1 ~ 5) 평가 체계
모든 작업에 거창한 검토 과정을 거치면 오히려 생산성이 떨어집니다. 반대로 중요한 작업에 검증이 없으면 참사가 발생합니다.
- Level 5 (Very Low - 단순 스타일/오타 수정):
보안이나 아키텍처 검토 없이 즉시 실행(Silent Mode)하여 빠른 템포 유지. - Level 1 (Critical - 결제, 인증, DB 마이그레이션):
무조건 상세 계획 수립 및 개발자 승인 후 실행(Explicit Mode). - 5단계(홀수)의 장점: 중간값(Level 3)이 존재하여 애매한 경계의 작업도 유연하게 분류 가능.
4-4. 동적 전문가(Parent) 매핑
요청에 따라 필요한 전문가를 실시간으로 유연하게 호출합니다:
- “로그인 폼 만들어줘” → UI/UX 전문가 투입
- “소셜 로그인 및 토큰 갱신 추가해줘” → 백엔드 + 보안 전문가 자동 동시 투입
4-5. 외부 지식(RAG/MCP) 및 3중 검증 파이프라인
최신 프레임워크(Next.js 15 등)나 특정 라이브러리의 최신 API 버전 이슈를 방지하기 위해 3단계 신뢰도 체크와 3중 검증을 거칩니다:
- 신뢰도 평가: 지식 확신도가 낮으면 임의로 추측하지 않고 MCP/문서 탐색을 우선 요청.
- Child 검증: 문법적 정합성 및 기본 동작 확인.
- Parent 검증: 보안 취약점, 성능 병목, 도메인 패턴 준수 확인.
- PM 검증: 전체 프로젝트 아키텍처와의 일관성 확인.
Part 5: 도입 전후(Before & After) 비교
| 구분 | 기존 프롬프트 방식 | PCIP Framework 적용 |
|---|---|---|
| 요청 전달 | 매번 보안, 에러 핸들링, 엣지 케이스를 길게 나열 | 핵심 요구사항만 자연스럽게 전달 |
| 실행 흐름 | 즉시 구현 → 결함 발견 → 수정 반복 (시간 낭비) | 사전 위험 분석 → 가이드 수립 → 원샷 구현 |
| 코드 품질 | 파편화되고 맥락 없는 코드 양산 | 프로젝트 아키텍처에 맞춘 일관된 구조 유지 |
| 유지보수성 | 배포 후 예상치 못한 사이드 이펙트 빈발 | 캐시 무효화, 트랜잭션 등 필수 로직 기본 탑재 |
Part 6: 시스템 프롬프트 적용 방법
PCIP 프레임워크는 사용 중인 AI 개발 환경의 시스템 규칙(Rules)에 아래 저장소의 프롬프트를 등록하여 즉시 사용할 수 있습니다.
- GitHub 저장소: saramjh/PCIP SystemPrompt.md
- 적용 위치:
- Cursor:
Settings→Rules for AI또는 프로젝트 루트의.cursorrules - Claude Code / Gemini CLI: System Instructions / Global Memory
- 기타 AI 어시스턴트: 새로운 세션 시작 시 시스템 프롬프트로 본문 전체를 입력
- Cursor:
마치며
AI를 단순한 자동완성 도구가 아니라, 맥락을 이해하고 협업하는 든든한 팀원으로 만들기 위한 시도였습니다. 복잡한 프로젝트를 진행 중이거나 AI의 잦은 엣지 케이스 누락으로 고민하셨던 개발자분들께 작은 도움이 되기를 바랍니다. 사용해 보시면서 개선할 점이 있다면 언제든 편하게 의견 남겨주세요!