Merge pull request #49 from kookmin-sw/feature/#48-side-panel-generator

jys705 · web-flow · commit 1c0b1897d035 · 2026-04-29T17:53:42.000+09:00
[#48][AI] side_panel 프롬프트 + Side Panel Generator
diff --git a/ai/prompts/side_panel.txt b/ai/prompts/side_panel.txt
@@ -1 +1,99 @@
-{# side_panel 프롬프트 템플릿 — Phase 3에서 구현 #}
+# 역할
+
+당신은 미국 법무부 소프트웨어 개발 생명주기 가이드(DOJ SDLC)를 기반으로 소프트웨어 프로젝트를 안내하는 AI 멘토다. 사용자는 소프트웨어 개발 경험이 많지 않은 대학생 또는 사이드 프로젝트 개발자다.
+
+이번 호출의 목적은 사용자가 클릭한 **일반 Step의 사이드패널 콘텐츠**를 생성하는 것이다. 사이드패널은 Step을 클릭했을 때 화면 우측에 열리는 가이드 패널이며, 사용자가 그 Step을 어떻게 진행할지 즉시 이해하도록 돕는다.
+
+> 필수 Step의 사이드패널은 DB에 사전 제작되어 있어 AI가 생성하지 않는다. 이 호출은 일반 Step 전용이다.
+
+# 출력 언어와 톤
+
+- 모든 출력은 **한국어**.
+- 초보자 친화적 표현. 전문용어·영문 약어가 꼭 필요하면 옆에 짧게 풀어 설명한다.
+- 단정·훈계조가 아니라 권유·안내조의 짧고 명확한 문장.
+- "함께 해봐요" 같은 빈말 대신 **무엇을, 어떻게 하는지**가 드러나는 행동지향 문장.
+
+# 출력 형식 (엄격)
+
+**오직 다음 JSON 한 덩어리만** 반환한다. 설명·서론·마무리·코드 펜스(```) 없이 순수 JSON만 출력한다.
+
+{{
+  "description": "...",
+  "recommended_methods": [
+    {{ "title": "...", "content": "..." }},
+    {{ "title": "...", "content": "..." }}
+  ],
+  "common_mistakes": [
+    {{ "mistake": "...", "bad_example": "...", "good_example": "..." }},
+    {{ "mistake": "...", "bad_example": "...", "good_example": "..." }}
+  ],
+  "one_line_tip": "..."
+}}
+
+규칙:
+- 위 4개 키만 사용한다. 추가 키 금지.
+- 모든 값은 한국어 문자열.
+
+# 각 필드 작성 가이드
+
+## 📖 `description`
+- **3~5문장**.
+- 이 Step에서 무엇을 하는지 + 왜 중요한지가 자연스럽게 이어지도록.
+- 사용자가 "아, 이걸 왜 해야 하는지" 한 번에 이해되어야 한다.
+
+## 🔥 `recommended_methods` (배열, 2~4개)
+각 항목은 정확히 두 키 `title`, `content`로만 구성한다.
+- `title`: 방법의 이름. **10~15자** 한국어. (예: "경쟁 서비스 찾아보기", "사용자 리뷰 모으기")
+- `content`: 구체적인 실행 방법을 **2~3문장**으로. "어떻게 하는가"가 분명히 드러나야 하며, 가능하면 도구·산출물·진행 단계가 등장하도록 한다.
+- 초보자가 **당장 시도해볼 수 있는 실용 기법**만 담는다. 고급·이론적 기법은 피한다.
+
+## ⚠️ `common_mistakes` (배열, 2~3개)
+각 항목은 정확히 세 키 `mistake`, `bad_example`, `good_example`로만 구성한다.
+- `mistake`: 자주 하는 실수를 한 줄로.
+- `bad_example`: ❌ 그 실수가 실제로 어떻게 나타나는지 짧고 구체적인 예. 한 문장이면 가장 좋다.
+- `good_example`: ✅ **같은 상황**을 올바르게 처리한 예. 비교가 되도록 bad_example과 같은 주제·맥락을 다룬다.
+
+## 💡 `one_line_tip`
+- 이 Step의 본질을 압축한 **한 문장**의 핵심 조언.
+- "꼭 기억해야 할 단 하나"를 담는다.
+
+# 콘텐츠 생성 원칙
+
+1. **RAG 우선** — `rag_context`에 의미 있는 청크가 있으면 그것을 기반으로 작성한다. 단어를 그대로 인용하지 말고, 의미를 흡수해 초보자 언어로 재서술한다.
+2. **RAG 폴백** — `rag_context`가 비었거나 "없음"이면 자체 지식으로 작성하되, **초보자 수준의 기법만** 추천한다.
+3. **프로젝트 맥락 반영** — 기간(`{duration_months}`개월), 인원(`{member_count}`명), 제약사항을 고려해 **실제로 실행 가능한 범위**만 추천한다. 짧은 일정에 몇 달 걸릴 활동을 제안하지 않는다.
+4. **현재 필수 Step과의 정합성** — 진행 중인 필수 Step이 있으면, 이 Step이 그 필수 Step의 충족(`fulfillment_aspects`)에 어떻게 기여하는지가 자연스럽게 드러나도록 작성한다.
+5. **히스토리 활용** — 의사결정 히스토리에 이미 Accept된 Step에서 다룬 내용은 중복 설명하지 말고, 그 위에서 한 걸음 나아가는 식으로 연결한다.
+
+---
+
+# 입력 데이터
+
+## 프로젝트 정보
+- 이름: {project_name}
+- 기간: {duration_months}개월
+- 인원: {member_count}명
+- 설명: {description}
+- 제약사항: {constraints}
+- 초기 아이디어: {initial_prompt}
+
+## 현재 Stage
+- Stage {stage_number}: {stage_name}
+
+## 클릭된 Step (사이드패널 생성 대상)
+- {target_step_name}
+
+## 의사결정 히스토리 (이미 Accept된 Step 목록, JSON)
+{decision_history}
+
+## 현재 진행 중인 필수 Step (없으면 "없음")
+{current_required_step_info}
+
+## RAG 검색 결과 (DOJ SDLC / 자체 문서)
+{rag_context}
+
+---
+
+# 출력
+
+위 모든 맥락을 반영하여, 위에서 명세한 JSON 한 덩어리만 출력하라.
diff --git a/ai/services/side_panel_generator.py b/ai/services/side_panel_generator.py
@@ -0,0 +1,129 @@
+"""사이드패널 콘텐츠 생성 서비스 (side_panel 시나리오, 일반 Step 전용).
+
+LLMClient + RAGClient를 조합하여, DOJ KB와 Custom KB 검색 결과를 합쳐
+프롬프트로 조립하고 Claude를 호출해 일반 Step 사이드패널 콘텐츠를 생성한다.
+필수 Step의 사이드패널은 DB 사전 제작이므로 이 서비스는 호출되지 않는다.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+from ai.clients.llm import LLMClient
+from ai.clients.rag import RAGClient
+from ai.prompts.template import PromptTemplate
+from ai.schemas.common import RetrievedChunk
+from ai.schemas.side_panel import SidePanelInput, SidePanelOutput
+
+logger = logging.getLogger(__name__)
+
+_SCENARIO = "side_panel"
+_NONE_LABEL = "없음"
+
+
+def _format_rag_context(
+    doj_chunks: list[RetrievedChunk],
+    custom_chunks: list[RetrievedChunk],
+) -> str:
+    """DOJ + Custom 검색 결과를 프롬프트용 텍스트로 합쳐 포맷팅."""
+    sections: list[str] = []
+
+    if doj_chunks:
+        sections.append("[DOJ SDLC]")
+        sections.extend(chunk.text for chunk in doj_chunks)
+
+    if custom_chunks:
+        sections.append("[자체 문서]")
+        sections.extend(chunk.text for chunk in custom_chunks)
+
+    if not sections:
+        return _NONE_LABEL
+
+    return "\n".join(sections)
+
+
+def _coerce(value: Any, default: str = _NONE_LABEL) -> str:
+    """None을 default 라벨로 변환."""
+    if value is None:
+        return default
+    return str(value)
+
+
+class SidePanelGenerator:
+    """side_panel 시나리오 — 일반 Step 사이드패널 콘텐츠 동적 생성."""
+
+    def __init__(self, llm: LLMClient, rag: RAGClient) -> None:
+        self.llm = llm
+        self.rag = rag
+
+    async def generate_side_panel(self, input_data: SidePanelInput) -> SidePanelOutput:
+        """입력을 받아 Claude로 사이드패널 콘텐츠를 생성한다.
+
+        흐름:
+            1) RAG 병렬 검색 (DOJ + Custom)
+            2) 프롬프트 조립
+            3) LLM 호출 → SidePanelOutput 검증
+        """
+        stage = input_data.current_stage
+        project = input_data.project_info
+        target = input_data.target_step
+
+        doj_query = f"Stage {stage.stage_number} {stage.name} {target.name}"
+        custom_query = target.name
+
+        doj_chunks, custom_chunks = await asyncio.gather(
+            self.rag.search_doj(doj_query),
+            self.rag.search_custom(custom_query),
+        )
+
+        decision_history_json = json.dumps(
+            [item.model_dump() for item in input_data.decision_history],
+            ensure_ascii=False,
+        )
+
+        if input_data.current_required_step is not None:
+            required_step_info = json.dumps(
+                input_data.current_required_step.model_dump(),
+                ensure_ascii=False,
+            )
+        else:
+            required_step_info = _NONE_LABEL
+
+        rag_context_text = _format_rag_context(doj_chunks, custom_chunks)
+
+        prompt = PromptTemplate.load_and_render(
+            _SCENARIO,
+            project_name=_coerce(project.name),
+            duration_months=str(project.duration_months),
+            member_count=str(project.member_count),
+            description=_coerce(project.description),
+            constraints=_coerce(project.constraints),
+            initial_prompt=project.initial_prompt,
+            stage_number=str(stage.stage_number),
+            stage_name=stage.name,
+            target_step_name=target.name,
+            decision_history=decision_history_json,
+            current_required_step_info=required_step_info,
+            rag_context=rag_context_text,
+        )
+
+        logger.info(
+            json.dumps(
+                {
+                    "event": "side_panel_generator_invoke",
+                    "project_id": project.project_id,
+                    "stage_number": stage.stage_number,
+                    "target_step_name": target.name,
+                    "doj_chunks": len(doj_chunks),
+                    "custom_chunks": len(custom_chunks),
+                    "has_required_step": input_data.current_required_step is not None,
+                    "prompt_len": len(prompt),
+                },
+                ensure_ascii=False,
+            )
+        )
+
+        return await self.llm.invoke(prompt, SidePanelOutput)
diff --git a/ai/tests/test_side_panel_generator.py b/ai/tests/test_side_panel_generator.py
