AI 문서 안내의 현재 구조와 유지보수
사용법 질문에는 권한과 문서 근거를 확인해 답하고, 처리 결과를 추정하는 질문으로 분류되면 실제 내역 확인을 안내합니다.
이 문서는 2026-10-14 PR #1246의 구현을 설명합니다. 배포·재색인·운영 활성화가 완료됐다는 기록은 아닙니다. 분류 버전은 chat-intent-v11-state-check, 답변 버전은 docs-guide-v21-state-check입니다.
원본 문서·색인·안내 범위의 차이
| 구분 | 역할 | 현재 범위와 근거 |
|---|---|---|
| docs | 사람이 읽고 관리하는 설명의 원본입니다. 생성 가이드는 HTML 원고를 수정한 뒤 Markdown으로 재생성합니다. | docs/ko/guides/와 fragments/입니다. 원고 관리 규칙은 문서 작성·갱신 기준를 따릅니다. |
| 색인 스크립트 | 가이드를 읽어 Voyage로 청킹·임베딩하고 S3 Vectors에 검색용 데이터로 저장하는 프로그램입니다. 별도의 가이드 내용을 수기로 작성하지 않습니다. | scripts/index-docs-guides.mjs의 파일 선택 규칙에 해당하는 Markdown 15개입니다. |
| 서버 문서 스냅샷 | 검색 결과의 원문 버전·본문·절을 대조하기 위해 빌드에 포함하는 생성 파일입니다. 벡터 DB를 대신하지 않습니다. | scripts/gen-ai-guidance-snapshot.mjs가 관리자·직원 앱·HR 문서 3개를 documents.generated.ts로 생성합니다. 외부 API를 호출하지 않습니다. |
| 안내 기능 정의 | 질문을 문서 위치·발췌 범위·필요 권한에 연결하는 설정입니다. 답변 본문이나 정답 목록이 아닙니다. | guidance/catalog.ts의 10개 기능입니다. 이 목록 밖 질문은 상세 안내 대상으로 정하지 않습니다. |
색인 대상 15개 문서와 안내 기능 10개는 서로 다른 단위입니다. 문서 전체가 벡터 DB의 색인 대상이어도 현재 안내 경로가 모든 구간을 검색·설명하는 것은 아닙니다. 내부 설계 문서인 docs/internal/, 기능 기록인 docs/ko/features/, 원고 HTML 자체도 이 색인 스크립트의 입력에 포함하지 않습니다.
색인 대상과 갱신 시점
스크립트는 docs/ko/guides 바로 아래의 .md 파일을 읽고 제외 목록을 적용합니다. 다음 표는 현재 파일 목록이며, 실행 기준은 스크립트와 실제 폴더입니다.
| 가이드 | 색인 대상 파일 |
|---|---|
| 관리자 | admin.md |
| 기능 변경 이력 | change-history.md |
| 고객사 온보딩 | customer-onboarding.md |
| 경영 대시보드 | dashboard.md |
| 직원 앱 | employee-app.md |
| 자주 묻는 질문 | faq.md |
| 총무 | general-affairs.md |
| HR 급여 시트 | hr.md |
| 사용자 가이드 메인 | index.md |
| 한국 급여 규정 | korean-payroll.md |
| 간호 스케줄러 | nurse-scheduler.md |
| 병원 온보딩 플레이북 | onboarding-playbook.md |
| 시트 양식 다운로드 | sheet-templates.md |
| 신규 병원 테스트 | test-guide.md |
| 사용 영상 | video-tutorials.md |
README.md, team-manager.md, inventory.md, getting-started.md는 명시적으로 제외합니다. 공개 여부를 바꾸면 색인 제외 목록과 VitePress의 srcExclude도 함께 검토합니다. 파일 수를 고정된 제품 계약으로 사용하지 않습니다.
색인에는 Voyage voyage-context-4, 자동 청킹 크기 512, 출력 차원 1024를 사용합니다. S3에는 청크 본문·문서 경로·URL을 메타데이터로 저장하고, 벡터 키에는 가이드 이름·원문 해시·청크 번호를 포함합니다. 현재 스크립트는 실행할 때 대상 문서를 모두 임베딩한 뒤 이전 키를 정리합니다. 해시가 있다는 이유로 변경 문서만 임베딩하는 증분 처리라고 해석하면 안 됩니다.
개발 환경의 .github/workflows/dev-sites.yaml은 develop에서 예약 또는 수동 실행하며, 문서 배포 성공 뒤 indexing-docs 작업으로 pnpm index:docs-guides를 실행합니다. 현재 예약은 평일 03:30 KST입니다. PR 푸시나 로컬 문서 빌드가 곧 색인 실행은 아닙니다. 이 명령은 Voyage API와 S3 쓰기를 수행하므로 로컬 무과금 검증 명령에 포함하지 않습니다.
안내 요청 처리
자동 안내가 활성화된 대화에서 Claude는 현재 질문·이전 질문·앱 정보로 사용법 안내, 실제 업무 조회·실행, 불명확한 요청을 구분합니다. 사용법이면 등록된 기능을 최대 3개 선택하고 질문 단계도 분류합니다. 실제 업무 요청은 기존 업무 도구 경로로 전달되며, 안내 답변을 했다는 사실이 등록·수정 실행을 의미하지 않습니다.
서버는 조직·기능 권한과 필요한 시트 접근 권한을 먼저 검사합니다. 검색어는 사용자 질문 원문이 아니라 선택한 기능의 공개 이름·설명입니다. S3 검색은 그 기능의 sourcePath로 제한하고, 지정된 절·발췌 경계만 답변 근거로 허용합니다. 부족한 청크는 인접 청크 조회로 보완하며 현재 스냅샷과 문서 해시·본문이 맞지 않으면 안내를 중단합니다.
Claude의 답변 생성에는 사용자 원문, 이전 질문, 앱 정보와 검증된 발췌를 전달합니다. 분류하면서 만든 재해석 질문은 전달하지 않습니다. 서버는 출처 ID·기능별 출처 포함·형식을 검사하며, 생성 중간 텍스트를 그대로 공개하지 않습니다. 이 검사는 답변 의미 전체의 정답 판정을 대신하지 않습니다.
현재 안내 가능한 10개 기능
기존 9개 기능에 직원 수정 1개를 추가했습니다. 기능 수는 벡터 검색의 기술적 한도가 아니라 현재 수동으로 연결한 문서·권한 범위입니다.
| 기능 ID | 설명 | 가이드·절 |
|---|---|---|
employee.edit.admin | 관리자 직원 정보 수정·재직 전환을 안내합니다. | admin.md#s4-2 |
employee.register.admin | 관리자 신규 직원 등록을 안내합니다. | admin.md#s4-1 |
leave.approval.admin | 관리자 휴가 승인·반려를 안내합니다. | admin.md#s7-3 |
attendance.admin | 관리자 근태 확인·수정을 안내합니다. | admin.md#s6-2 |
leave.request.employee | 직원 앱 본인 휴가 신청을 안내합니다. | employee-app.md#s4 |
attendance.employee | 직원 앱 본인 출퇴근·근무 확인을 안내합니다. | employee-app.md#s3 |
sheet.overview | HR 시트 화면 구성을 안내합니다. | hr.md#s1-1 |
sheet.lifecycle | HR 시트 작업 상태 변경을 안내합니다. | hr.md#s1-2 |
sheet.cell.edit | HR 시트 셀 편집·서식을 안내합니다. | hr.md#s3-2 |
sheet.filter | HR 시트 필터·정렬·찾기를 안내합니다. | hr.md#s3-4 |
같은 절의 별도 업무까지 전부 지원한다는 뜻은 아닙니다. 예를 들어 직원 등록의 임시 비밀번호 SMS 발송, 근태 수정의 정정 요청 승인 등은 별도 권한의 절차이므로 해당 발췌에서 제외합니다. 세부 권한과 경계의 기준은 guidance/catalog.ts입니다. 문서 내용이 바뀌면 해당 연결과 경계도 다시 확인해야 합니다.
상태 질문과 모델 호출
| 질문 단계 | 현재 동작 |
|---|---|
usage | 일반 사용법·위치·조건을 문서 근거로 설명합니다. |
pre_submission | 최종 제출 전 확인창의 취소·돌아가기·계속 진행을 문서로 설명합니다. |
outcome_inference | 최종 요청을 시도했거나 시도 여부가 불명확한 상황에서 화면만으로 성공·미접수·취소를 추정하지 않습니다. 실제 처리 결과를 확인하기 전 재실행하지 말라는 고정 안내를 반환합니다. |
질문 단계는 모델이 분류합니다. 상태 확인 분기의 로컬 통과가 모든 자연어 상태 질문을 정확하게 분류한다는 증거는 아닙니다. 등록 기능의 상태 질문은 권한·검색 검증을 통과하면 검증된 출처와 함께 고정 안내를 반환하고 답변 생성 호출을 생략합니다. 미등록 상태 질문은 문서 링크 없이 고정 안내를 반환합니다. 권한·검색 검증이 실패하면 해당 실패 안내가 먼저 반환될 수 있습니다.
정상 안내의 Claude 호출은 통상 분류 1회와 답변 생성 1회입니다. 이미 자동 분류한 결과를 안내 함수에 전달한 경우에는 그 함수가 분류를 반복하지 않습니다. 답변 뒤 상시 의미 검토 호출은 없습니다. 제출 누락·일부 형식 오류는 기존 한 차례 복구를 허용하며, 분류 오류 처리나 외부 전송 재시도까지 포함하면 실제 호출 수는 달라질 수 있습니다. Voyage 임베딩과 S3 검색 비용은 Claude 호출과 별도입니다. 이번 로컬 검증에서 새 모델 호출을 하지 않았으므로 실제 비용 절감률을 제시하지 않습니다.
이번 PR은 기존 답변 생성 프롬프트를 유지하고, 분류 단계에 질문 종류와 상태 확인 분기만 추가합니다. 채택하지 않은 퓨샷·프롬프트 후보, 371개 수동 업무 목록, 전수 평가 실행기와 저장 결과는 최종 변경에서 제외했습니다. 상시 검토 모델 호출도 추가하지 않습니다.
문서 변경 시 유지보수
- 생성 가이드는
docs/ko/guides/fragments/의 원고를 수정하고pnpm gen:docs-guides를 실행합니다. 직접 작성하는 가이드는 원본 Markdown을 수정합니다. 기존 절 앵커가 밀리지 않는지 확인합니다. - 관리자·직원 앱·HR 가이드 변경은
pnpm gen:ai-guidance로 서버 문서 스냅샷도 동기화합니다. 이 명령은 로컬 생성만 수행합니다. - 기존 10개 기능의 문서 절·발췌 경계·권한 연결을 검사합니다. 새 문서를 색인 대상으로 추가한 것만으로 새 안내 기능이 등록되지는 않습니다. 전체 가이드 자유 검색은 현재 구현 범위에 포함하지 않습니다.
- 아래 로컬 검증을 실행합니다. 모델 분류·답변을 대체한 분기 검사와 실제 모델 품질 평가는 구분합니다.
- 배포 시 서버 스냅샷과 실제 벡터 인덱스의 원문 버전을 맞춥니다. 문서나 기능 정의가 바뀌면
GUIDANCE_VERSION도 달라집니다. 운영 환경은 검토 버전 일치와 조직 활성화 설정을 별도로 확인해야 합니다. 문서 작성·PR 병합만으로 활성화 완료를 선언하지 않습니다.
로컬 검증과 근거
다음 명령은 로컬 생성 일치와 테스트를 확인합니다. 실제 모델 평가 실행기나 pnpm index:docs-guides는 포함하지 않습니다.
pnpm check:docs-guides
pnpm check:ai-guidance
pnpm --filter @hereby/api test src/services/ai/guidance src/services/ai/guide src/services/ai/agent.auto-guidance.test.ts src/services/ai/providers/anthropic.test.ts테스트는 모델과 검색 응답을 대체하여 수정·등록 질문의 문서 연결, 상태 확인 분기, 권한·발췌 범위, 출처·형식 검사를 실행합니다. 일반 사용법과 제출 전 질문은 기존 답변 생성으로 진행하고, 처리 결과 추정으로 분류된 질문은 고정 안내로 끝나는지 확인합니다. 이 테스트는 실제 자연어 분류·생성 답변의 정답률이나 현재 검색 인덱스 상태를 측정하지 않습니다.
최종 변경과 검증 범위는 PR 구현·검증 기록에 있습니다. 실패를 조사할 때는 문서 안내 진단을 사용합니다. 배포·인덱스 동기화·운영 활성화와 실제 사용자 화면 검증은 별도 확인 대상입니다.
코드와 과거 설계의 관계
구현을 확인할 시작점은 다음과 같습니다. 경로는 저장소 루트 기준입니다.
| 확인 대상 | 구현 위치 |
|---|---|
| 색인 대상·청킹·저장·오래된 키 정리 | scripts/index-docs-guides.mjs |
| 서버 원문 스냅샷 생성 | scripts/gen-ai-guidance-snapshot.mjs |
| 기능·문서·권한 연결 | packages/api/src/services/ai/guidance/catalog.ts |
| 자동 분류와 질문 단계 | packages/api/src/services/ai/guidance/intent.ts, prompts.ts |
| 권한 확인·검색·답변·상태 분기 | packages/api/src/services/ai/guidance/turn.ts, availability.ts |
| Voyage와 S3 검색·인접 청크 복원 | packages/api/src/services/ai/guide/retrieval.ts, retrieval-normalize.ts |
| 운영 검토 버전·활성화 | packages/api/src/services/ai/guidance/settings.ts |
초기 AI 아키텍처와 초기 가이드 기능 기획의 pgvector·증분 색인·전체 가이드 검색은 당시 설계입니다. 현재 문서 안내에 그 계획이 모두 구현됐다고 해석하지 않습니다. 현재 구현 판단에는 이 문서와 해당 버전의 코드를 사용합니다.