13 KiB

Raw Blame History

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

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

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

A-1. 실측 결과

.claude/hooks/ 디렉토리: 부재. hook은 scripts/ 루트에 bash 스크립트로 배치 후 .claude/settings.json의 hooks.*.command에서 직접 참조하는 구조.
현재 등록 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
미등록 hook 타입: PostToolUse·SessionEnd·SubagentStart·SubagentStop 는 현 settings.json에 전혀 등록되지 않음. Claude Code 최신 schema 상 PostToolUse·SessionEnd 는 지원 확인됨 (등록만 하면 동작).
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.
검증 스크립트 부재 항목: verify_log_paths.sh(PD 지시 로그 산출물 경로 실존 검증) — 미구현 (pm-auditor I1 제안).

A-2. 팀 관점 기록 누락 리스크 (실측 기반)

#28 Unity MCP 전환 사례: 커밋 db64310 제목에 "시뮬레이션 MCP 전환"이 1줄 포함되었으나, 대화로그 2026-04-17.md·공유/소통/PM→개발팀/에 기술 배경·대안 비교·의사결정 근거 문서가 연결되지 않음. 활성 지시 테이블 비고란에 "2026-04-17 Unity MCP 방향으로 전환"만 추가되어, 다른 세션에서 "왜 전환됐는지" 복원 불가.
공유/소통/개발팀→PM/2026-04-17_Unity_MCP_시뮬레이션_기술검토_개발팀.md 는 생성됨 — 단, 이 문서가 #28 로그의 산출물 경로 컬럼에 추가 기재되었는지 교차 확인 필요(PM 점검 권고).
공용 모듈·인터페이스 변경 시 사전 공유(P13) 자동 감지 메커니즘 없음. 코어코드/BT.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):

#!/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

리스크 및 비용:

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

B-2. 신규 hook 제안 2종

B-2-1. `PostToolUse` hook — md 대규모 변경 시 대화로그 엔트리 리마인더

목적: Edit/Write 로 .md 파일을 100줄 이상 수정한 직후, 당일 대화로그에 관련 엔트리가 있는지 감지하여 부재 시 리마인더. P24 누락을 사후 즉시 감지.

settings.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):

#!/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

리스크:

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

B-2-2. `SessionEnd` hook — 세션 종료 시 기록 누락 최종 감사

목적: 세션 종료 직전 (a) 당일 대화로그 부재 (b) 활성 지시 상태 변화 있었으나 갱신 누락 (c) .live/ 더미 미반영분 감지 → 경고 출력.

settings.json 추가:

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

스크립트 요지:

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

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

B-3. `SubagentStart`/`SubagentStop` hook 가능성 검토

현 Claude Code schema: 표준 hook 타입에 SubagentStart·SubagentStop 은 공식 등록 항목 아님 (2026-04-17 기준 확인). Task 도구 호출·응답은 PreToolUse·PostToolUse 에서 matcher: "Task" 로 포착 가능.
대체 설계: PostToolUse matcher "Task" 로 Agent 호출 종료 감지 → 해당 Agent 가 응답에 "PD 지시 로그 #N → 완료 갱신" 문구 포함 여부 자동 스캔 → 부재 시 PM 경고. C27 강제 메커니즘 구현 가능.
구현 비용: 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.

로직:

# 당일 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. 커밋 메시지·대화로그 연동 표준 (팀장 재량 수용 가능)

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

C-2. 공용 모듈 변경 사전 공유 자동화 (PM 조율 필요)

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

C-3. 설계 문서화 누락 감지 (팀장 재량)

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

C-4. PD님 결정 필요 사안 (본 보고 범위 아님)

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

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

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

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

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

F. 차단 요인

없음 — 본 점검은 실측 + 설계안 수준. 구현 착수는 PM 조율 후.
주의: 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님 결정 떠넘기기 표현 부재. "어떻게 할까요?" 없음. 자체 설계안 제시형 작성.

13 KiB Raw Blame History Unescape Escape