건설도면 프로젝트 문서작성규칙
| 항목 | 내용 |
|---|---|
| 제정 | 2026년 11월 14일 |
| 대상 | C:\work\서치독_프로젝트\ 전체 문서(**/*.md) — repos/(외부 클론), output/history/(아카이브), 업무폴더/(일일 업무기록·{YYMMDD}_ 네이밍) 제외 |
R1 파일명 순서 규칙 (RULE)
모든 문서 파일명은 {SEQ}_{파일명} 형식으로 짓는다.
{SEQ}: 2자리 일련번호(00~99). 읽는 순서 = 번호 오름차순. 전 프로젝트에서 유일.{파일명}: 기존 파일명 그대로(접두·접미 관례는 R2 유지).- 새 문서는 현재 최대 번호 + 1로 부여한다. 읽기 순서를 바꿀 때만 기존 번호를 재부여하며,
이때 전 문서의 상호참조 링크를 일괄 갱신한다(부분 갱신 금지).
- 아카이브(
output/history/), 외부 클론(repos/), 일일 업무기록(업무폴더/—{YYMMDD}_{파일명}규칙 별도 적용)에는 SEQ를 부여하지 않는다. - 규칙 문서 자신은
00_을 쓴다(무엇보다 먼저 읽으므로).
R2 명명 관례 (기존 유지)
- 산출물 보고서·설계문서:
KIKUM_건설도면_{주제}_{YYYYMMDD}.md— SEQ 뒤에 붙인다.
예) 06_KIKUM_건설도면_로컬보완환경_구성및검증_20261113.md
- 환경·운영 문서(README, 연동 가이드): 원래 이름 앞에 SEQ만 붙인다. 예)
10_README.md
R3 내용 규칙 (기존 관례의 명문화)
- 판정 기준을 문서마다 명시한다 — 기본 기준: "실제와 동일한 증거로 동작하는가".
가능/불가/보류를 구분하고, 불가는 원인(기술 제약·자원 부재·사람 합의 필요)을 분리해 기술한다.
- 증거 우선: 수치·결과는 실측만 기재하고, 설정·버전을 함께 남긴다(11.1절 요건).
예측·해석·판단은 근거와 구분해 표기한다. 실패와 오인식 사례도 삭제하지 않고 기록한다.
- 재현 경로: 모든 실험 결과에는 재현 스크립트 경로(또는 명령)를 남긴다.
- 상호참조는 전체 경로 링크로 쓴다. 개명 시 R1에 따라 일괄 갱신.
- 검증기·검사 결과는 기계 판정과 사람 판정을 분리한다
(validation_status vs review_status 등, 가이드 18.2절).
현재 SEQ 배정표 (2026-11-14)
| SEQ | 파일 | 위치 | 성격 |
|---|---|---|---|
| 00 | 00_문서작성규칙.md | 루트 | 이 문서 |
| 01 | 01_KIKUM_건설도면_업무태스크_실행계획_20261113.md | output/ | 전체 설계(T01~T28·게이트) |
| 02 | 02_KIKUM_건설도면_업무적응_상세가이드_20261113.md | output/ | 절차 상세(12절 흐름·17~21절) |
| 03 | 03_KIKUM_건설도면_OpenSearch_문제별_해결범위_분석_20261113.md | output/ | 기술 범위 분석 |
| 04 | 04_KIKUM_건설도면_보완기술_구현방안_20261113.md | output/ | 보완방안(S01~S10) |
| 05 | 05_KIKUM_건설도면_AWS에뮬레이터_시나리오검증_20261113.md | output/ | 1차 실험(에뮬레이터) |
| 06 | 06_KIKUM_건설도면_로컬보완환경_구성및검증_20261113.md | output/ | 2차 실험(하이브리드+A그룹+T27) |
| 07 | 07_KIKUM_건설도면_시나리오충족도_종합판정_20261114.md | output/ | 3차 종합 판정 |
| 08 | 08_README.md | aws-emulator/ | 에뮬레이터 환경 개요·시작 |
| 09 | 09_INTEGRATION.md | aws-emulator/ | 타 세션 연동 가이드 |
| 10 | 10_README.md | aws-emulator/local/ | 로컬 하이브리드 환경 운영 |
| 11 | 11_KIKUM_건설도면_잔여문제_설계필요성검토_20261114.md | output/ | 잔여 문제 목록+설계 필요성 검토(D-1~D-3 판정) |
| 12 | 12_KIKUM_건설도면_실환경전환_아키텍처설계_20261114.md | output/ | D-1 전환 아키텍처(초안 v0.1, 가설 병기) |
| 13 | 13_KIKUM_건설도면_외부요청패키지_20261114.md | output/ | 발송용 요청서 3종(샘플·구성 질의·합의 안) |
| 14 | 14_KIKUM_건설도면_전체아키텍처_에뮬레이터구분_20261116.drawio | output/ | 전체 아키텍처 drawio 6시트(에뮬 가능/부분/불가 색 구분) |
| 15 | 15_KIKUM_건설도면_기술용어집_20261117.md | output/ | 기술용어집·기술요소 총람(최초 통합, 플로우 도식 포함) |
| 16 | 16_KIKUM_건설도면_기술용어집_20261117.html | output/ | 15의 HTML 판(검색 필터·SVG 내장, 오프라인 동작) |
| 17 | 17_KIKUM_건설도면프로젝트_양식템플릿_20261117.md | output/ | kikum.xyz/physical-ai-motion 양식 템플릿(팔레트·레이아웃 실측) |
| 18 | 18_KIKUM_건설도면프로젝트_학습자료_20261117.md | output/ | 학습자료 문서(7단원+공인 URL 목록+다운로드 기록) |
| 19 | 19_KIKUM_건설도면프로젝트_시각화학습자료_20261117.html | output/ | A2 모션 학습 지도 9페이지(17 템플릿 준수·오프라인·시트9 발행 목차) |
| 20 | 20_KIKUM_건설도면_AI서포트데이터엔지니어링_구성환경_20261117.md | output/ | AI 서포트 데이터엔지니어링 구성환경(표준 골격←실물 사상·상태 3값) |
| 21 | 21_KIKUM_건설도면_하이브리드검색_시각화학습자료_20261117.html | output/ | OpenSearch 하이브리드 검색 A2 모션 학습자료(공식 문서 14편 분석·9시트) |
| 22 | 22_KIKUM_건설도면_시맨틱하이브리드튜토리얼_시각화학습자료_20261117.html | output/ | 공식 튜토리얼 단계별 A2 모션 학습자료(실습 전문 분석·3방식 순위 대조·9시트) |
| 23 | 23_KIKUM_건설도면_유튜브전사_파이프라인체크리스트_20261117.md | output/ | 유튜브 전사→블로그 게시→학습자료 파이프라인 가능/불가 체크리스트(실측 판정) |
| 24 | 24_KIKUM_건설도면_MCP팀_요청서_유튜브전사_블로그게시_20261117.md | output/ | MCP팀 요청서 — YouTube 전사 MCP·AI Ready 블로그 게시 MCP 사양 시안(수용 완료) |
| 25 | 25_261117_신규기능_외부연동_가이드.md | output/ | 수신 문서 — MCP팀 외부연동 가이드(stable-261117·원문 보존) |
| 26 | 26_KIKUM_건설도면_MCP팀가이드_수용및연동준비_20261117.md | output/ | 가이드 수용 판정·연동 준비 체크리스트(단계별 재판정·파일럿 계획) |
| 27 | 27_KIKUM_건설도면_DA-DE_협업인터페이스_20261117.md | output/ | DA(분석·평가)↔DE(데이터 담당) 태스크별 협업 인터페이스(초안·T03 확정 대기) |
| 28 | 28_KIKUM_건설도면_유튜브전사_파일럿3편_학습자료_20261117.md | output/ | 유튜브 전사 파일럿 3편 학습자료(OpenSearchCon 발표·발췌 원문 인용·프로젝트 대조) |
| 29 | 29_KIKUM_건설도면_유튜브전체_링크페이지_20261117.html | output/ | 채널 전체 711편 학습자료 링크페이지(원문 영상 링크 보존·검색 필터·상태 표시) |
| 30 | 30_KIKUM_건설도면_외부링크전사_목록화태스크_20261118.md | output/ | 외부링크 전사 목록화 태스크(A/B/C 판별 기준·문서형 22건+채널 1건 대기열·파이프라인 정의) |
| 31 | 31_KIKUM_건설도면_DA-DS_협업인터페이스_20261118.md | output/ | DA(분석·평가)↔DS(평가 설계·품질 분석) 태스크별 협업 인터페이스(초안·T03 확정 대기·27 DA-DE의 DS 대응물) |
| 32 | 32_KIKUM_건설도면_AWS문서_학습요약본_D2-D5_20261118.md | output/ | 30호 대기열 D2~D5 AWS 문서 4건 v3 학습요약본(SQS/SNS/EventBridge·EventBridge·Lambda·Lambda×SQS — 12호 전환 설계 직결) |
| 33 | 33_KIKUM_건설도면_MCP팀요청서_서버웨지티켓_20261118.md | output/ | ASR 서버 무응답 웨지 결함 티켓(재현 2회·가설 병기·요청 4건 — 25호 가이드 §7.2 채널 발송 대기) |
| 34 | 34_KIKUM_건설도면_MCP팀결함보고_배치응답_ASR품질_20261118.md | output/ | MCP팀 결함 보고 #2(batchrun 무음 실패·ASR 언어 오인식 완전실패 1+부분노이즈 만연·쇼츠·라이브 범위 협의 — 33 웨지 티켓과 분업) |
| — | (아카이브) | output/history/ | SEQ 미부여 |
읽기 흐름: 00 규칙 → 01~04 설계 → 05~07 실험·판정(시계열) → 11 잔여 문제·설계 검토 → 12 전환 설계 → 13 요청 패키지(현재 기준 최신 결론) → 08~10 환경 운영.
빠른 요약이 필요하면 07·11부터 읽고 필요한 문서로 거슬러 올라간다. (11~13은 07 직후가 논리 순서이나 R1 최대번호+1 규칙을 우선해 번호를 부여했다.)
발행 체계(2026-11-17 추가): 프로젝트 공개 명칭은 건설도면(문서 내 문구 일괄 변경 완료 — 루트 폴더명 서치독_프로젝트는 경로 보호를 위해 유지). 모든 .md 문서는 양식 템플릿(17) 준수 문서 뷰어로 변환되어 output/html/{동일 SEQ}.html에 있고, 19 시트9 발행 목차에서 전체 접근·drawio·다운로드 자료까지 연계된다. drawio 링크는 브라우저에서 바로 렌더링되는 인라인 뷰어 페이지(output/html/viewer_*.html, 로컬 내장 공식 뷰어 assets/viewer-static.min.js — 오프라인 유지)로 열린다. 재변환은 output/html/publish.sh 1회 실행(문서+뷰어 동시 갱신).
14 drawio는 12 전환 설계의 도식 참고본이다(판정 수치·근거는 본문 05·06·07이 원천). 구버전 도식 KIKUM_건설도면_전체시스템_아키텍처_데이터흐름_20261113.drawio(SEQ 이전 작성, 5탭)은 태스크 맵 등 상세가 남아 있어 보존한다.