BurningTimesAi/공유/소통/완료/2026-04-17_업무공유체계_점검_클라이언트팀.md

---
type: 점검보고
from: 클라이언트팀장
to: PM
date: 2026-04-17
status: 진행중
tags: [#자율작업, #개발, #진행중, #자동화설계, #업무공유체계]
---

# 업무공유체계 전수 점검 — 클라이언트팀장 (기술 자동화 관점)

## A. 현황 실측 (hook·script·settings.json schema)

### A-1. 실측 결과
1. **`.claude/hooks/` 디렉토리**: **부재**. hook은 `scripts/` 루트에 bash 스크립트로 배치 후 `.claude/settings.json`의 `hooks.*.command`에서 직접 참조하는 구조.
2. **현재 등록 hook 5종 (settings.json)**:
   - `PreToolUse`: `scripts/auto_approve.sh` (권한 자동 승인)
   - `SessionStart` × 5: `git fetch+merge`(인라인), `inbox_scan.sh`, `change_digest.sh`, `live_session_load.sh`, `pm_context_restore.sh`
   - `UserPromptSubmit` × 3: `git_fetch_throttle.sh`, `hold_watch.sh`, `live_inject.sh`
3. **미등록 hook 타입**: `PostToolUse`·`SessionEnd`·`SubagentStart`·`SubagentStop` 는 **현 settings.json에 전혀 등록되지 않음**. Claude Code 최신 schema 상 `PostToolUse`·`SessionEnd` 는 지원 확인됨 (등록만 하면 동작).
4. **`scripts/` 현존 14종**: `agent_sync.sh`·`auto_approve.sh(+py)`·`change_digest.sh`·`context_brief.sh`·`git_fetch_throttle.sh`·`hold_watch.sh`·`inbox_scan.sh`·`live_inject.sh`·`live_session_load.sh`·`nas_post_receive.sh`·`pm_context_restore.sh`·`stale_check.sh`·`verify_setup.ps1`.
5. **검증 스크립트 부재 항목**: `verify_log_paths.sh`(PD 지시 로그 산출물 경로 실존 검증) — **미구현** (pm-auditor I1 제안).

### A-2. 팀 관점 기록 누락 리스크 (실측 기반)
1. **#28 Unity MCP 전환 사례**: 커밋 `db64310` 제목에 "시뮬레이션 MCP 전환"이 1줄 포함되었으나, 대화로그 `2026-04-17.md`·`공유/소통/PM→개발팀/`에 기술 배경·대안 비교·의사결정 근거 문서가 **연결되지 않음**. 활성 지시 테이블 비고란에 "2026-04-17 Unity MCP 방향으로 전환"만 추가되어, 다른 세션에서 **"왜 전환됐는지" 복원 불가**.
2. **`공유/소통/개발팀→PM/2026-04-17_Unity_MCP_시뮬레이션_기술검토_개발팀.md`** 는 생성됨 — 단, 이 문서가 #28 로그의 산출물 경로 컬럼에 **추가 기재되었는지 교차 확인 필요**(PM 점검 권고).
3. **공용 모듈·인터페이스 변경 시 사전 공유(P13)** 자동 감지 메커니즘 **없음**. `코어코드/NerdNavis.Framework/Runtime/**` 변경은 클라이언트·차기 프로젝트에 직접 영향이나, 현재 **수동 공유에만 의존**.

---

## B. 기술 자동화 개선안 구체 설계 (최우선)

### B-1. `scripts/verify_log_paths.sh` 설계안 (pm-auditor I1 대응)

**목적**: PD 지시 로그 활성 테이블에 기재된 `산출물 경로` 컬럼의 모든 파일·디렉토리 경로가 실존하는지 자동 검증. 존재하지 않는 경로(유령 문서, 이동·삭제 후 갱신 누락) 즉시 감지.

**호출 시점**: `SessionStart` hook 말미 + `UserPromptSubmit` 주기 실행(예: `git_fetch_throttle.sh`와 같은 throttle 적용). 매 턴 실행은 과도 → 1시간 throttle 권장.

**의사코드** (bash):
```bash
#!/bin/bash
# scripts/verify_log_paths.sh — PD 지시 로그 산출물 경로 실존 검증
# 근거: pm-auditor I1, C13·P18·P19·C29-4
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
cd "$REPO_ROOT" || exit 0

THROTTLE_FILE="/tmp/verify_log_paths.last"
NOW=$(date +%s)
LAST=$(cat "$THROTTLE_FILE" 2>/dev/null || echo 0)
[ $((NOW - LAST)) -lt 3600 ] && exit 0   # 1시간 throttle
echo "$NOW" > "$THROTTLE_FILE"

MISSING=0
for LOG in 공유/PD_지시_트래킹/*_PD_지시_로그.md; do
  # "## 활성 지시" ~ "## 완료 아카이브" 범위만 추출
  awk '/^## 활성 지시/,/^## 완료 아카이브/' "$LOG" | \
  # 테이블 행의 "산출물 경로" 컬럼(4번째 |) 추출
  grep -oE '`[^`]+\.(md|cs|json|csv|xlsm|xlsx|txt|sh|py|ps1)`|`[^`]+/`' | \
  tr -d '`' | sort -u | while read PATH_CANDIDATE; do
    # 상대경로·절대경로·글롭 분기
    [ -z "$PATH_CANDIDATE" ] && continue
    case "$PATH_CANDIDATE" in
      /*) FULL="$PATH_CANDIDATE" ;;
      *) FULL="$REPO_ROOT/$PATH_CANDIDATE" ;;
    esac
    if [ ! -e "$FULL" ] && [ ! -d "$FULL" ]; then
      echo "⚠️ [verify_log_paths] MISSING: $LOG → $PATH_CANDIDATE"
      MISSING=$((MISSING+1))
    fi
  done
done

[ "$MISSING" -gt 0 ] && echo "🚨 PD 지시 로그 산출물 경로 ${MISSING}건 실존 확인 실패 (PM 확인 필요)"
exit 0
```

**리스크 및 비용**:
1. 한글 경로·글롭 패턴(예: `Runtime/Core/**`) 파싱이 bash에서 까다로움 — `**` 는 `ls -d` 로 별도 처리 필요.
2. 복합 산출물 비고란(예: "A 완료분 + B 완료분" 멀티 경로)의 파싱 품질이 핵심 — 정규식 튜닝 필요.
3. **구현 비용**: 스크립트 자체는 작으나 기존 로그 형식 편차 흡수에 테스트 라운드 필요.
4. **오탐 리스크**: 이동된 경로·일시 미생성 경로로 false positive 가능 → 상태 `완료`인 항목만 검증 대상으로 좁히는 것이 안전.

### B-2. 신규 hook 제안 2종

#### B-2-1. `PostToolUse` hook — md 대규모 변경 시 대화로그 엔트리 리마인더
**목적**: Edit/Write 로 `.md` 파일을 100줄 이상 수정한 직후, 당일 대화로그에 관련 엔트리가 있는지 감지하여 부재 시 리마인더. P24 누락을 **사후 즉시 감지**.

**settings.json 추가**:
```json
"PostToolUse": [
  {
    "matcher": "Edit|Write|MultiEdit",
    "hooks": [
      {"type": "command", "command": "bash scripts/postuse_log_reminder.sh 2>/dev/null || true"}
    ]
  }
]
```

**스크립트 초안** (`scripts/postuse_log_reminder.sh`):
```bash
#!/bin/bash
# PostToolUse: md 대규모 변경 감지 → 당일 대화로그 존재 여부 확인
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
cd "$REPO_ROOT" || exit 0

# 최근 5분 내 수정된 .md 중 100줄 이상 diff
RECENT_BIG=$(git diff --stat HEAD 2>/dev/null | \
  awk '$1 ~ /\.md$/ && ($3+0)>=100 {print $1}')
[ -z "$RECENT_BIG" ] && exit 0

TODAY=$(date +%Y-%m-%d)
HAS_LOG=0
for DIR in 공유/대화로그/*/; do
  [ -f "${DIR}${TODAY}.md" ] && HAS_LOG=1 && break
done
if [ "$HAS_LOG" -eq 0 ]; then
  echo "⚠️ [postuse] md 대규모 변경 감지되었으나 당일 대화로그 부재 — P24 작성 권고"
  echo "   변경 파일: $RECENT_BIG"
fi
exit 0
```

**리스크**:
1. Edit/Write 매 호출마다 `git diff --stat` 는 비용 있음 — throttle(10초) 권장.
2. 매우 큰 작업 중 과도 출력 → `stderr` 로 전환 또는 부재 최초 1회만 출력.

#### B-2-2. `SessionEnd` hook — 세션 종료 시 기록 누락 최종 감사
**목적**: 세션 종료 직전 (a) 당일 대화로그 부재 (b) 활성 지시 상태 변화 있었으나 갱신 누락 (c) `.live/` 더미 미반영분 감지 → 경고 출력.

**settings.json 추가**:
```json
"SessionEnd": [
  {
    "matcher": "",
    "hooks": [
      {"type": "command", "command": "bash scripts/session_end_audit.sh 2>/dev/null || true"}
    ]
  }
]
```

**스크립트 요지**:
1. 당일 `공유/대화로그/*/$(date +%Y-%m-%d).md` 존재 여부.
2. `.live/` 중 README.md 외 파일 존재 여부(미반영 의심).
3. 당일 커밋 건수 vs 대화로그 엔트리 건수 대략 비교.
4. **모드 B 감사 자동 트리거 신호**: pm-auditor 호출 권고 메시지 출력.

**리스크**: SessionEnd 는 사용자가 세션을 실제 종료한 시점에만 발화 — 앱 강제 종료·충돌 시 미발화 가능성. 100% 강제 메커니즘은 아니므로 SessionStart 의 복원 체크(`pm_context_restore.sh`)와 **쌍으로 운용** 필요.

### B-3. `SubagentStart`/`SubagentStop` hook 가능성 검토
1. **현 Claude Code schema**: 표준 hook 타입에 `SubagentStart`·`SubagentStop` 은 **공식 등록 항목 아님** (2026-04-17 기준 확인). `Task` 도구 호출·응답은 `PreToolUse`·`PostToolUse` 에서 `matcher: "Task"` 로 포착 가능.
2. **대체 설계**: `PostToolUse` matcher `"Task"` 로 Agent 호출 종료 감지 → 해당 Agent 가 응답에 "PD 지시 로그 #N → 완료 갱신" 문구 포함 여부 자동 스캔 → 부재 시 PM 경고. **C27 강제 메커니즘 구현 가능**.
3. **구현 비용**: Agent 응답 본문은 hook stdin 으로 들어오므로 jq 파싱 필요. Windows bash 환경에서 jq 설치 여부 선결 확인.

### B-4. 커밋-대화로그 정합성 자동 감지 (#28 재발 방지)
**목적**: `feat(core):`·`feat(client):`·`refactor:` 등 **의미 있는 prefix** 의 커밋이 당일 발생했으나 대화로그에 관련 엔트리 부재 시 감지.

**구현 위치**: `scripts/session_end_audit.sh` 내부 또는 별도 `scripts/commit_log_match.sh`.

**로직**:
```bash
# 당일 feat/refactor/fix(core) 커밋 추출
BIG_COMMITS=$(git log --since="$(date +%Y-%m-%d) 00:00" --oneline | \
  grep -E "^\w+ (feat|refactor|fix\(core\)|feat\(core\))")
# 대화로그 엔트리 개수
LOG_ENTRIES=$(grep -c "^## \[" 공유/대화로그/*/$(date +%Y-%m-%d).md 2>/dev/null | \
  awk -F: '{s+=$2} END{print s+0}')
# 커밋 2건 이상인데 엔트리 1건 이하면 경고
```

**리스크**: 커밋 1건이 여러 엔트리에 대응 또는 그 반대 — 정확한 1:1 매칭은 어려움. **비율 기반 경고**로 설계 (완벽 매칭 아님, 누락 의심 신호 수준).

---

## C. 비기술적 개선안 (코드 변경 기록 체계)

### C-1. 커밋 메시지·대화로그 연동 표준 (팀장 재량 수용 가능)
1. **제안**: 의미 있는 기술 결정이 포함된 커밋(`feat(core):`·`refactor:` 등)은 **커밋 메시지 하단에 `Log: 공유/대화로그/<프로젝트>/YYYY-MM-DD.md#HH:MM` 형식 참조 라인 필수**.
2. **권한**: 팀장 재량 (C20-1 일반 커밋 범위). PM 상의만 거치면 즉시 적용 가능.

### C-2. 공용 모듈 변경 사전 공유 자동화 (PM 조율 필요)
1. **제안**: `코어코드/NerdNavis.Framework/Runtime/**`·`Editor/**` 수정 시 `PreToolUse` hook 이 **변경 사실을 `공유/소통/개발팀→기획팀/`·`개발팀→PM/` 에 draft 로 append** (수동 보완 전제).
2. **권한**: PM 조율 필요 — 타 팀(기획팀·서버팀) 통보 자동화는 팀 간 합의 필요.

### C-3. 설계 문서화 누락 감지 (팀장 재량)
1. **제안**: 코어 프레임워크 디렉토리에 신규 `.cs` 파일 추가 시 `프로젝트/코어프레임워크/` 에 대응 설계 문서(`*_설계_*.md`) 존재 여부 자동 확인. 부재 시 P18 위반 경고.
2. **권한**: 팀장 재량, 개발팀 내부 규약 수준.

### C-4. PD님 결정 필요 사안 (본 보고 범위 아님)
- 본 점검은 기술 자동화 설계 중심. PD님 직접 결정이 필요한 헌법급 규칙 개정(예: C31 에 "PostToolUse 자동 감사" 의무 포함 여부)은 **PM이 팀장 논의 종합 후 안건화** 판단.

---

## D. 클라이언트팀 세션 맥락 유지 방안 (자체 관점)

1. **자기 세션 맥락**: 클라이언트팀장은 Agent 호출마다 새로 인스턴스화되며, 직전 호출 기억 없음 → **응답 시 반드시 실측 결과만 보고**(C23). 필요 시 PM 프롬프트에 "이전 호출 산출물 경로" 명시 요청.
2. **기술 스택 변경 이력**: `.mcp.json`·`Packages/manifest.json`·`코어코드/NerdNavis.Framework/Runtime/**` 변경은 **커밋 메시지 + 대화로그 + `공유/소통/개발팀→PM/` 보고 3중 기록** 원칙 제안 (팀장 재량).
3. **의존성 변경**: Unity 패키지·코어 프레임워크 버전 업은 P15(의존성·환경 변경 공유) 준수 — 현재 자동 감지 없음, `PostToolUse` hook 으로 `manifest.json` 수정 시 경고 추가 권장.

---

## E. 우선순위 권고 (기술 관점)

1. **즉시 착수 권장 (구현 비용 낮음·효과 큼)**:
   - B-1 `verify_log_paths.sh` (pm-auditor I1 대응, 본 팀 작성 가능)
   - B-2-1 `PostToolUse` md 대규모 변경 리마인더
2. **PM 조율 필요**:
   - B-2-2 `SessionEnd` hook + pm-auditor 자동 호출 연계
   - B-4 커밋-대화로그 정합성 감지
3. **타 팀 합의 필요**:
   - C-2 공용 모듈 변경 타 팀 자동 통보
4. **보류 (schema 확인 필요)**:
   - B-3 Subagent hook — Claude Code schema 추가 조사 후 재검토

---

## F. 차단 요인

1. **없음** — 본 점검은 실측 + 설계안 수준. 구현 착수는 PM 조율 후.
2. **주의**: B-1~B-2 실제 구현 시 Windows Git Bash 환경 테스트 필수 (한글 경로·jq 가용성 등).

---

## G. 산출물 경로
- 본 문서: `공유/소통/개발팀→PM/2026-04-17_업무공유체계_점검_클라이언트팀.md`

## H. 제약 준수 선언
- **C23**: 모든 실측은 Bash 도구 호출 결과 기반 (hook 부재·script 14종·settings.json 본문).
- **C29**: 단일 의사결정 요청 없음. 각 개선안에 팀장 재량/PM 조율/PD님 결정 구분 명시.
- **C30**: 본 점검은 조직 레포 내 문서 작성 — git 상태 영향 없음.
- **C31**: PD님 결정 떠넘기기 표현 부재. "어떻게 할까요?" 없음. 자체 설계안 제시형 작성.