문서 관계도 — 기획 문서 의존 그래프

최종 업데이트: 2026-08-08

기획 문서를 고치기 전과 후에 보는 문서다. 전에는 "무엇을 함께 읽어야 하는가", 후에는 "무엇을 함께 고쳐야 하는가" 를 알려 준다. 그래프의 단일 원본이며, 각 문서 헤더의 바뀌면 갱신 블록은 이 표에서 파생된 요약이다.

0. 왜 있는가

하위 문서만 고치고 상위·형제 문서를 안 고치는 사고가 반복됐다. (2026-08-02 전수 확인)

셋 다 역참조 경로를 따라가지 않아서 생겼다. 이 문서는 그 경로를 명시하고, check-doc-graph.ps1이 어긋남을 기계로 잡는다.

1. 층위

문서는 네 층이고, 의존은 대체로 아래에서 위로 흐른다.

게임기획코어는 그림에서 뺐다. 16개 문서 전부와 양방향이라 선을 그으면 읽을 수 없다. 어느 문서를 고치든 게임기획코어 5장(확정/미확정 현황)은 항상 확인한다.

굵은 의존 (허브 제외)

화살표는 전파 방향이다 — A ──> B 는 "A가 바뀌면 B를 고쳐야 한다".

graph TD
    작업슬롯 --> 자원채취
    작업슬롯 --> 산업레벨
    작업슬롯 --> 캐릭터
    작업슬롯 --> 게임UI

    자원채취 --> 산업레벨
    자원채취 --> 낚시
    자원채취 --> 농사
    자원채취 --> 벌목
    자원채취 --> 채굴
    자원채취 --> 사냥
    자원채취 --> 아이템
    자원채취 --> 특성

    산업레벨 --> 낚시
    산업레벨 --> 농사
    산업레벨 --> 벌목
    산업레벨 --> 채굴
    산업레벨 --> 사냥
    산업레벨 --> 캐릭터
    산업레벨 --> 게임UI

    캐릭터 --> 작업슬롯
    캐릭터 --> 자원채취
    캐릭터 --> 특성
    캐릭터 --> 아이템
    캐릭터 --> 거래

    특성 --> 자원채취
    특성 --> 작업슬롯
    특성 --> 캐릭터
    특성 --> 퀘스트
    특성 --> 채굴

    아이템 --> 거래
    거래 --> 아이템
    거래 --> 자원채취
    거래 --> 캐릭터
    거래 --> 퀘스트
    거래 --> 진행및성장

    퀘스트 --> 특성
    퀘스트 --> 거래
    퀘스트 --> 진행및성장

순환이 정상이다. 캐릭터 ↔ 작업슬롯, 아이템 ↔ 거래처럼 서로를 참조하는 쌍이 여럿 있다. 전파할 때는 이미 방문한 문서를 다시 열지 않는 것으로 멈춘다 (3장).

2. 전체 그래프

2.1 이 문서가 바뀌면 갱신할 곳 (역참조)

고친 뒤에 보는 표다. 왼쪽을 고쳤으면 오른쪽을 전부 열어 본다.

⚠️ 자원채취·산업레벨·특성·거래가 위험 지대다. 한 줄을 고쳐도 10곳 이상이 흔들린다. 이 넷을 고칠 때는 check-doc-graph.ps1을 반드시 돌린다.

2.2 이 문서를 쓸 때 참고할 문서 (정참조)

고치기 전에 보는 표다. 왼쪽을 쓰려면 오른쪽을 먼저 읽는다.

3. 전파 규칙 — 재귀적으로 따라간다

한 단계만 보고 멈추지 않는다. 갱신한 문서가 또 다른 문서의 전파원이 되기 때문이다.

전파(고친 문서):
    큐 = [고친 문서]
    방문 = {}
    while 큐:
        문서 = 큐.pop()
        if 문서 in 방문: continue     ← 순환은 여기서 멈춘다
        방문.add(문서)

        for 대상 in 역참조[문서]:      ← 2.1 표
            대상을 연다
            if 이번 변경이 대상의 서술을 낡게 만들었나?
                대상을 고친다
                대상의 "최종 업데이트"를 오늘로 바꾼다
                큐.push(대상)          ← 고쳤으면 그 문서에서 또 퍼진다
            else:
                넘어간다               ← 열어 보고 안 고치는 것이 정상이다

3.1 무엇이 "낡게 만드는" 변경인가

전부를 다 고칠 필요는 없다. 아래에 해당할 때만 대상 문서를 손댄다.

4. 문서 밖으로 나가는 그래프 — 엑셀·코드

기획 문서끼리만 맞으면 절반이다. 확정된 기획은 엑셀과 코드로도 흘러야 한다. 2026-08-02에 발견된 불일치의 절반이 이 경로에서 끊겨 있었다.

전파 순서는 한 방향이다.

기획 문서 확정  →  GameDesign/Excel/*.xlsx  →  generate-tables.ps1  →  생성물  →  서버 코드

⚠️ 엑셀만 앞서 나가면 "미구현"이 아니라 "오동작"이 된다. 2026-08-01에 드롭 시트가 레벨별로 갈라졌는데 DropTableCatalog가 IndustryLevel을 읽지 않아, Lv1 슬롯에서 Lv5 아이템이 나오는 상태가 됐다. 엑셀 구조를 바꿀 때는 그 시트를 읽는 서버 코드를 같은 작업 단위로 본다.

기획이 확정됐는데 코드가 못 따라가면 tasks/에 남긴다. 문서에는 반드시 ❌ 미구현 (일감 T-0XX)를 적는다 — 적어 두지 않으면 다음 사람이 "구현됐다"고 읽는다.

5. 검사 도구

# 커밋 전 — 이번에 고친 문서에서 출발하는 전파만 본다 (git 기준). 평소엔 이것을 쓴다
powershell -File GameDesign/check-doc-graph.ps1 -Changed

# 전수 점검 — 저장소 전체의 미전파를 훑는다 (경고가 많이 뜬다)
powershell -File GameDesign/check-doc-graph.ps1

# 그래프 덤프 — 이 문서의 2장 표를 갱신할 때
powershell -File GameDesign/check-doc-graph.ps1 -Graph

# 각 문서 헤더의 "바뀌면 갱신" 블록을 실제 그래프에 맞춰 다시 쓴다
powershell -File GameDesign/check-doc-graph.ps1 -Fix

-Changed가 기본 사용법이다. 커밋 전에 알고 싶은 것은 "방금 고친 문서가 전파됐는가" 하나뿐이다.

5.1 확인 완료 — 전파하지 않기로 한 것 (2026-08-02)

전수 정리 후 남은 경고 11건은 전부 확인했고, 고칠 것이 없어 남겨 둔 것이다. 날짜 역전은 사실이지만 이번 변경이 이 문서들의 서술을 낡게 만들지 않았다.

이 표가 경고를 소음이 아니라 기록으로 만든다. 다음에 같은 경고를 보면 여기부터 확인하고, 그 사이 새 변경이 있었는지만 판단하면 된다.

갱신일 역전은 오류가 아니라 경고다. "A를 고쳤지만 B에는 영향이 없었다"가 정상적으로 존재하기 때문이다. 경고를 보고 사람이 판단한다. 다만 경고가 쌓여 배경 소음이 되면 검사가 죽는다 — 확인했으면 B의 날짜를 올리거나 왜 전파하지 않았는지 문서에 한 줄 남긴다.

6. 문서를 추가·삭제할 때

문서 이름은 항상 한글이다. Excel·DataLog만 코드가 경로를 참조해 예외다. → CLAUDE.md "이름 규칙"

Window Simulator · 문서 관계도 · 2026-08-02