mxchen-xyz/knowledge-graph-skill-zh

지식 그래프 배치 생성기

📌 버전 기록

버전	날짜	변경 내용
2.2.0	2026-09-02	대규모 프로젝트 전체 업그레이드 실전 경험 : ① 골격 카드 업그레이드 전략 - 사용자가 "보충 필요 항목이 너무 많음/규칙이 너무 간단함" 이라고 피드백하면 전체 업그레이드 트리거, 영역별로 자식 에이전트 병렬 할당 + 주 에이전트가 출력 모니터링(grep 남은 보충 필요 수), 에이전트 정체 시 인계하여 보충; ② mermaid 노드 레이블에 중첩 괄호 금지(렌더링 실패 1순위 원인) 및 배치 정규식 수정 스크립트; ③ 자식 에이전트의 모듈 간 상대 경로 오류 쉬움(../.. 계층), 최종 검사 시 반드시 이중 링크 검증 실행; ④ 업그레이드 후 통계 및 README 업데이트 반영
2.1.0	2026-09-01	Obsidian wiki 링크 경로 규범 수정(중요) : Obsidian의 [[...]] wiki 링크는 ../ 상대 경로를 지원하지 않음(../는 노트 이름으로 간주되어 클릭 불가), 모두 지식 베이스 루트에서 시작하는 전체 경로(`[[영역/모듈/기능.md
2.0.0	2026-08-24	Obsidian 이중 링크 호환성 수정 : 다섯 번째 배치 품질 검사에 "점 표기법 구문 금지 + 링크별 상대 경로 구문 분석 검증" 추가, 생성된 지식 베이스가 Obsidian에서 정상적으로 이동 가능
1.0.0	초기 버전	5배치 배치 생성 전략(L1+L2 골격 → L3 모듈 인덱스 → 핵심 기능 카드 → 나머지 기능 골격 → 전체 품질 검사) 기본 기능

개요

대규모 프로젝트를 위한 지식 엔지니어링. 프로젝트가 완전한 코드/문서를 갖추고, 기능 노드가 50개 이상이며, 한 번에 수백 개 노드의 완전한 지식 베이스를 생성해야 할 때, 배치 전략에 따라 효율적으로 생성하여 단일 출력 과부하를 방지합니다. 모든 파일 내용은 business-knowledge-graph-generator 스킬에 정의된 템플릿 규범(references/templates.md)을 따라야 합니다.

사용 시기

• 기능 수가 50개를 초과하는 대규모 프로젝트
• 이미 완전한 프로젝트 코드 디렉터리 구조 + 핵심 코드 파일 내용(배치로 제공 가능)
• 한 번에 수백 개 노드의 완전한 지식 베이스를 생성해야 하는 경우

입력 요구 사항: 완전한 프로젝트 코드 디렉터리 구조 + 핵심 코드 파일 내용 제공(배치로 제공 가능).

배치 처리 전략

기능 수가 50개를 초과하면 다음 순서로 5개 배치로 처리합니다:

첫 번째 배치: L1 + L2 골격(전체 구조) — 예상 출력 6~20개 파일

1. knowledge/_index.md 생성(L1 전체 그림)
2. 각 영역에 대해 <영역>/_index.md 생성(L2 영역 그림)
3. 품질 검사: 모든 영역과 모듈이 포함되었는지 확인, 누락 없음

두 번째 배치: L3 모듈 인덱스(기능 목록) — 예상 출력 20~50개 파일

1. 각 모듈에 대해 <영역>/<모듈>/_index.md 생성(L3 모듈 그림)
2. 품질 검사: 각 모듈의 기능 목록이 완전한지 확인, 모든 기능이 명명되었는지 확인

세 번째 배치: 우선순위 높은 기능 카드(핵심 프로세스) — 예상 출력 20~30개 파일

1. 시스템의 핵심 기능 식별(사용자가 가장 많이 사용하는 20% 기능, 예: 로그인, 주문, 결제)
2. 이러한 기능에 대한 완전한 L4 카드 생성(프로세스, 규칙, 이벤트, 종속성, 코드 위치 포함)
3. 품질 검사: 핵심 프로세스에 예외 분기 포함, 코드 위치가 줄 번호까지 정확

네 번째 배치: 나머지 기능 골격 카드 — 예상 출력 50~200+개 파일

1. 나머지 기능에 대한 최소 카드 생성(최소한 Frontmatter + 기능 설명 + 기본 규칙 포함)
2. 상태: 보충 필요 표시, 추후 수동 완성을 위해 남겨둠
3. 품질 검사: 모든 기능에 해당 .md 파일이 있는지 확인, 기능 누락 없음

다섯 번째 배치: 전체 품질 검사 및 인덱스 업데이트

1. 모든 이중 링크가 Obsidian 호환 상대 경로([[../모듈/기능.md|별칭]])이고, [[영역.모듈.기능]] 점 표기법 구문이 없는지 확인
2. 순회 검증: 각 링크를 현재 파일 기준으로 해석한 후, 대상 .md 파일이 반드시 존재해야 함
3. 모든 끊어진 링크 표시, 수정 목록 생성
4. 각 계층 _index.md의 통계 숫자 업데이트(모듈 수, 기능 수)
5. knowledge/README.md 사용 설명 생성

우선순위 판단 규칙

우선순위	판단 기준	예시 기능
핵심	사용자 일상 사용 > 80% 시나리오, 금융 보안 관련	로그인, 주문, 결제, 환불
중요	사용자 일상 사용 30%~80% 시나리오, 데이터 관리 관련	주문 조회, 배송 추적, 정보 수정
일반	관리 백엔드 기능, 저빈도 작업, 설정류	상품 분류 관리, 로그 조회, 보고서 생성

출력 요구 사항

1. 배치별로 출력, 각 배치 완료 후 진행 상황 보고, 사용자 확인 후 다음 배치 진행
2. 각 배치 출력 시, 이번 배치에서 생성된 파일 목록 나열
3. 세 번째 배치(핵심 기능) 완료 후 일시 중지, 사용자가 다음 배치 중점 영역을 지정할 때까지 대기
4. 모든 파일 내용은 business-knowledge-graph-generator의 references/templates.md에 정의된 템플릿 규범을 따라야 함

배치 보고 형식

## 제 X 배치 완료 ✅

**생성 파일 수**: XX개
**관련 영역**: 영역A, 영역B
**파일 목록**:

- knowledge/영역A/_index.md
- knowledge/영역A/모듈A/_index.md
- ...

**다음 배치 계획**: XXX 영역의 핵심 기능 카드 생성

계속 진행하시겠습니까?

주의 사항

• 배치 전달: 프로젝트가 100개 이상의 기능을 가지면, 먼저 L1 및 L2 골격을 완성한 후, 점진적으로 L3로 드릴다운하고, 마지막으로 L4를 배치 생성
• 코드 읽기 제한: 코드 파일이 너무 많으면, 사용자에게 먼저 핵심 모듈의 5~10개 주요 파일을 제공하도록 요청하고, 나머지는 디렉터리 구조 설명만으로 충분
• 수동 보충: 스킬이 80%의 내용(구조, 프로세스, 규칙 프레임워크)을 생성하지만, 구체적인 역사적 문제 기록 및 담당자 정보는 사용자가 수동으로 보충하도록 안내

실전 경험 (2026-09-01 jetlinks 프로젝트에서 축적)

1. Obsidian 링크는 반드시 라이브러리 루트 경로 사용 + .md 접미사 없음(가장 중요): Obsidian의 wiki 링크는 ../ 상대 경로를 지원하지 않음(../는 노트 이름으로 간주됨), 또한 .md 접미사를 지원하지 않음([[Note.md]]는 "Note"가 아닌 "Note.md"라는 노트로 간주되어 클릭 불가). 모든 링크는 [[영역/모듈/기능|별칭]](knowledge/ 루트에서 출발, .md 작성 안 함)으로 통일, mermaid 다이어그램에서는 일반 텍스트 노드 사용(A[기능] --> B[기능]), [[...]] 구문 금지.
2. 자식 에이전트 429 속도 제한 다운그레이드: 대규모 탐색/생성 시 자식 에이전트가 빈도 제한(429)을 트리거할 수 있음. 이 경우 주 세션에서 직접 생성으로 다운그레이드: 먼저 Glob/Grep으로 모든 Controller의 @RequestMapping 및 HTTP 메서드 어노테이션(줄 번호까지 정확)을 찾은 후, 파일별로 작성.
3. 품질 검사 스크립트는 코드 블록을 건너뛰어야 함: L4 카드 내 "링크 규범" 예제가 종종 백틱 코드 블록에 작성되므로, 품질 검사 정규식은 먼저 `...` 와 mermaid 블록 내용을 제거해야 함. 그렇지 않으면 예제가 끊어진 링크로 잘못 보고될 수 있음.
4. 기능 수 재기입 메커니즘: L2 인덱스의 모듈 기능 수는 예상치이며, L3 생성 후 실제 값으로 대체, 다섯 번째 배치에서 스크립트를 사용하여 L2 통계 열과 L1 규모 통계를 자동 재기입.
5. 배치 생성 스크립트 사용: 네 번째 배치 골격 카드(100+ 파일)는 Python 스크립트를 사용하여 L3 인덱스 테이블에서 정규식으로 기능 이름/유형/설명을 추출하고 배치로 작성하여, 이름과 링크 일관성을 보장. 파일별 수동 작성보다 효율적이고 오류 가능성 낮음.

실전 경험 (2026-09-02 대규모 프로젝트 전체 업그레이드에서 축적)

6. 골격 카드 업그레이드 전체 트리거, 호출 대기하지 않음: 사용자가 "보충 필요/규칙 과도하게 간단"에 불만을 표시하면 전체 업그레이드 트리거, 영역별 배치, 모든 골격 카드를 완전한 카드 상세도로 업그레이드(business skill의 "L4 카드 상세도 기준" 참조).
7. 병렬 자식 에이전트 영역별 할당 + 주 에이전트 모니터링: 각 영역에 하나의 자식 에이전트 할당(prompt에 템플릿 예제 + mermaid 철칙 + 코드 조사 요구 사항 포함); 주 에이전트는 grep -rl "상태: 보충 필요" <영역> | wc -l로 남은 보충 필요 수를 주기적으로 확인하고, 에이전트가 정체(일정 시간 새 파일 출력 없음)되면 직접 인계하여 보충, 기다리지 않음.
8. mermaid 노드 레이블에 중첩 괄호 금지(렌더링 실패 1순위 원인): flowchart 노드 [..]/{..} 내에 ()가 나타나면(예: A[Foo(x)]), "Expecting SQE, DOUBLECIRCLEEND..." 구문 분석 오류 발생; 함수 시그니처 매개변수는 삭제하거나 공백으로 구분. 배치 수정: 정규식을 사용하여 mermaid 블록만 스캔하고, [label(args)]를 [label args]로 대체(괄호 제거, 쉼표는 공백으로 변경).
9. 자식 에이전트의 모듈 간 상대 경로 오류 쉬움: 자식 에이전트가 모듈 간 링크를 작성할 때 ../.. 계층 계산 오류는 빈번한 실수(예: 거래관리/거래로그/에서 시세데이터/관심종목관리/로의 링크는 ../../시세데이터/관심종목관리/_index.md여야 하는데 ../관심종목관리/로 잘못 작성됨); 최종 검사 시 반드시 이중 링크 검증 스크립트를 실행하여 끊어진 링크 목록을 작성하고 하나씩 수정.
10. 최종 검사 삼위일체: 업그레이드 완료 후 ① 이중 링크 완전성 스크립트(모든 md를 순회하며 [[...]] 상대 경로 해석 및 대상 존재 확인) ② mermaid 괄호 스캔 ③ 보충 필요 잔여 개수 확인(grep -rl "상태: 보충 필요" | wc -l 결과 0); README 통계 업데이트 후 전달.

골격 카드 업그레이드 작업 가이드

knowledge/에 이미 많은 골격 카드가 존재하며 업그레이드가 필요한 경우:

1. 잔여 수 통계: grep -rl "상태: 보충 필요" knowledge/*/ | wc -l   (영역별 세분화)
2. 영역별로 자식 에이전트 병렬 할당(각 prompt에는 다음 포함: 템플릿 예제 절대 경로, mermaid 철칙,
   코드 조사 요구 사항 "최소 1-2개의 실제 함수명+줄 번호, 찾을 수 없으면 '확인 중' 표시 및 허위 생성 금지", 출력 보고서 형식)
3. 주 에이전트 주기적 확인: find 최근 mtime 파일 / grep 남은 보충 필요 수; 정체 시 인계
4. 최종 검사: 이중 링크 검증 스크립트 + mermaid 괄호 스캔 + 보충 필요 개수 제로화
5. README 통계 및 각 계층 _index 통계 숫자 업데이트

리소스

• business-knowledge-graph-generator/references/templates.md: L1~L4 템플릿 규범(반드시 따라야 함)