ai/data/

Poco의 RAG 파이프라인(Bedrock Knowledge Base + S3 Vectors)에 인덱싱되는 장기 지식(long-term knowledge) 원본 저장소.

이 폴더의 마크다운 파일들은 팀이 직접 S3로 업로드한 뒤 Bedrock Knowledge Base의 두 개 Data Source로 인덱싱되며, Claude가 사용자 응답을 생성할 때 관련 청크를 실시간 검색해 프롬프트에 주입합니다.

1. 폴더 구조

ai/data/
├── doj/                    → KB-A 데이터 소스: DOJ SDLC Guidance Document (Jan 2003)
│   └── *.md                  원문 PDF를 마크다운으로 변환한 파일들
│
└── custom/                 → KB-B 데이터 소스: 팀 자체 제작 가이드 문서
    ├── glossary/             용어 사전 (1 파일 = 1 개념)
    └── technique/            기법 가이드 (1 파일 = 1 기법)

2. 데이터 소스 2개 분리 — 설계 원칙과 근거

Poco의 Bedrock Knowledge Base는 단일 KB 안에 두 개의 Data Source를 등록합니다. 같은 KB 아래 있지만 서로 다른 S3 prefix (doj/ vs custom/)를 가리키도록 분리되어 있으며, 런타임에 data_source_id 필터로 한쪽만 검색할 수 있도록 설계되었습니다.

왜 분리했나

구분 doj/ (KB-A) custom/ (KB-B)
답하는 질문 유형 “이 Stage에서 뭘 해야 해?” (절차·산출물·활동 범위) “그걸 어떤 방법으로 해?” / “이 용어가 뭐야?” (기법·용어)
성격 표준 절차서 (What to do) 팀 교과서 + 실무 멘토 (How to do / What it means)
변경 빈도 거의 없음 (PDF 고정) 지속 추가·개선 (팀이 가이드를 새로 쓸 때마다)
문서 형태 PDF 1개(DOJ 원문)를 통째로 청킹 마크다운 파일 여러 개 (1 파일 = 1 개념 단위)
출처 미국 법무부(DOJ) 공공 간행물 팀 자체 저작 (SWEBOK 토픽 구조 참조)

만약 하나의 KB·단일 Data Source로 섞으면?

한 KB 안에 두 종류 문서를 섞어 인덱싱하면, 쿼리 하나에 두 성격의 청크가 뒤섞여 반환됩니다. 예를 들어 “Stage 3에서 유스케이스를 어떻게 작성해야 하는가?” 라는 질문에 DOJ 원문 청크(절차 서술)와 팀 가이드 청크(기법 설명)가 섞여 오면, LLM이 “어느 쪽이 더 권위 있는 답인가” 를 판단해야 합니다. 이 판단이 매 호출마다 흔들리면 안내의 일관성이 무너집니다.

Data Source를 물리적으로 분리하고, 시나리오별로 명시적으로 한쪽만 검색하도록 하면 이 오염이 원천 차단됩니다.

코드 레벨에서는 RAGClient.search()가 data_source_id 파라미터로 분기하며, 호출 시점에 어느 쪽을 쓸지 결정합니다.

3. doj/ — DOJ SDLC Guidance Document

개요

미국 법무부(U.S. Department of Justice)가 2003년 1월에 배포한 Systems Development Life Cycle Guidance Document를 마크다운으로 변환한 파일 모음입니다. 공공 소프트웨어 개발의 표준 프로세스를 정의한 공식 문서이며, Chapter 1~10의 구조로 10단계 Phase를 상세히 기술합니다.

Poco에서의 역할

청킹 전략

DOJ 원문 PDF는 Chapter 단위로 마크다운 파일을 분리했으며, Bedrock Knowledge Base의 기본 청커가 이를 고정 크기 단위로 재분할합니다. Stage/Phase별 메타데이터는 검색 정확도가 충분하여 별도로 주입하지 않았습니다.

라이선스

public domain (17 U.S.C. § 105 — 미국 연방정부 저작물). 상업적 사용·수정·배포에 제약이 없으며, 원본 출처는 각 마크다운 파일 상단에 명시되어 있습니다.

4. custom/ — 팀 자체 제작 가이드 문서

개요

팀이 직접 작성한 가이드 문서 모음입니다. SWEBOK V4.0a (2024, IEEE Computer Society)의 토픽 구조를 학술적 뼈대로 참조했으며, 원문은 저작권 보호 대상이므로 인용·탑재하지 않고 토픽 구조만 참고했습니다.

왜 자체 문서를 따로 만드는가

일반적인 LLM은 소프트웨어 공학 지식을 폭넓게 학습한 상태입니다. “사용자 인터뷰를 하세요” 같은 답은 잘합니다. 그러나 소규모 팀(1~10명)·단기 프로젝트(1~12개월) 맥락에 맞춘 구체적 안내는 약합니다:

이런 질문에 LLM이 답하면 중대형 기업팀 기준으로 답하는 경향이 있고, 초심자에게는 과도한 추천이 됩니다. 팀 자체 가이드는 정확히 이 빈칸을 메웁니다.

4개 약점 영역

자체 가이드는 다음 4개 영역을 집중 커버하도록 작성되었습니다:

영역 핵심 문제
A. 팀 규모 캘리브레이션 LLM이 중대형 기업팀 기준으로 답해서 소규모 팀에 과도한 추천이 나옴
B. 안티패턴 “그만하세요” LLM은 “더 많이 도와주려는” 구조라 “여기까지만 하면 충분” 의 브레이크가 없음
C. 수치 기준 “얼마나” “인터뷰 하세요” 까지는 잘 말하지만 “몇 명, 몇 분” 같은 실행 가능한 수치는 모호함
D. 한국어 전문 용어 영문 직역 정의는 잘하지만 한국어 실무 뉘앙스가 약함

14편 중 13편이 영역 B(안티패턴)를 커버합니다. LLM이 절대 해주지 않는 “이건 도입하지 마” 의 컷오프를 명시적으로 제공하는 것이 Poco RAG의 핵심 차별점입니다.

폴더 구조

custom/
├── glossary/                   용어 사전 (1 파일 = 1 용어)
│   ├── functional-requirement.md
│   ├── non-functional-requirement.md
│   ├── use-case.md
│   └── ...
│
└── technique/                  기법 가이드 (1 파일 = 1 기법)
    ├── interview.md
    ├── brainstorming.md
    ├── prototyping.md
    └── ...

집중 배치

14편 중 11편이 Stage 3(요구사항 정의)과 Stage 4(설계)에 배치되어 있습니다. 이 구간이 “SWEBOK 권위 강 × LLM 약점 강” 의 교집합이기 때문입니다. 요구사항·설계 단계는 “얼마나 상세히, 어떤 도구로, 몇 페이지 분량으로” 같은 스케일 판단이 필요한데, LLM의 디폴트 답이 가장 부적절해지는 영역입니다.

청킹 전략

각 마크다운 파일을 1 파일 = 1 청크 = 1 개념 원칙으로 설계했습니다. 한 파일 안에 여러 개념을 섞지 않음으로써, 특정 개념을 찾는 쿼리가 정확히 해당 청크만 반환하도록 했습니다.

라이선스

팀 자체 저작물이며, SWEBOK V4.0a의 토픽 구조만 참조(원문 미인용)했습니다.

5. 업데이트 절차

이 폴더의 파일이 추가·수정되면 다음 작업을 이어서 해야 Claude가 새 내용을 참조할 수 있습니다.

  1. S3 업로드 AWS 콘솔 또는 CLI로 해당 파일들을 S3 버킷의 doj/ 또는 custom/ prefix 아래 업로드합니다.

  2. Bedrock Knowledge Base Sync AWS 콘솔 → Bedrock → Knowledge bases → (해당 KB 선택) → Data source 탭 → doj 또는 custom data source 선택 → Sync 버튼 클릭. 임베딩 재생성에 수 분 소요됩니다. Sync 상태가 Ready로 돌아오면 runtime에서 즉시 반영됩니다.

  3. 로컬 검증 (선택)

    python -m ai.latency_simulator --runs 1

    를 실행해 새 콘텐츠가 응답에 반영되는지 확인합니다. 특정 용어가 등장하는지 검증하는 스크립트는 ai/tests/ 디렉토리 참조.

6. 참고 문서