하네스: ILSOS_PrismaticRD_PTOP 분석 팀

목표

ILSOS_PrismaticRD_PTOP(PtoP)의 3계층 아키텍처, 구현 상세, 빌드 최적화를 종합 분석하고 개선안 제시. 분석 전용 하네스 — 소스 코드를 수정하지 않는다. 코드를 실제로 고치는 작업은 code_Agent를 쓴다.

트리거

다음 요청 시 orchestrate-ptop-harness 스킬을 사용한다.

"PTOP 프로젝트 전체 분석" / "PTOP 전체 점검" / "PTOP 구조 파악"
"PTOP 아키텍처와 구현 분석" / "PTOP 팀 조율"
후속: "PTOP 재분석", "아키텍처만 다시", "빌드 분석만 다시", "이전 결과 기반으로"

단일 영역만 필요하면 개별 스킬을 직접 쓴다 — analyze-ptop-architecture / analyze-ptop-implementation / optimize-ptop-build.

팀 구성

에이전트	담당	사용 스킬	산출 (`_workspace/`)
`ptop-lead`	3계층 아키텍처·디바이스 스택·시퀀스 의존성	`analyze-ptop-architecture`	`01_ptop_architecture.md`
`ptop-developer`	시퀀스 상태머신·타이밍·Rx 체인·에러 처리	`analyze-ptop-implementation`	`02_ptop_implementation.md`, `03_device_integration.md`
`build-devops-engineer`	멀티 구성 빌드·의존성·CI/CD	`optimize-ptop-build`	`04_build_analysis.md`, `05_cicd_pipeline.yml`, `06_ptop_build_optimization.md`

통합 보고서: _workspace/00_PTOP_HARNESS_SUMMARY.md

실행 모드

서브 에이전트 병렬 + 의존 순차. 이 환경에는 TeamCreate/TeamDelete 도구가 없으므로 Agent(기동, model: "opus") + SendMessage(소통) + _workspace/_progress.md 파일(진행 원장)로 구성한다.

ptop-lead와 build-devops-engineer는 병렬, ptop-developer는 lead 산출 완료 후 순차.

구성 요소

Agents: .claude/agents/ptop-lead.md, ptop-developer.md, build-devops-engineer.md Skills: .claude/skills/orchestrate-ptop-harness/, analyze-ptop-architecture/, analyze-ptop-implementation/, optimize-ptop-build/ Workspace: _workspace/ (중간 산출물 보존 — 감사 추적용)

하네스를 고칠 때 — 소비처 확인 의무

라운드마다 같은 유형의 회귀가 반복됐다. 값을 늘려놓고 그 값을 읽는 쪽을 안 고치는 것이다.

실제 사례	늘린 것	안 고친 소비처
`ubisam-qa` 검증항목 11 신설	표 행 10 → 11	성공 기준 "10개"
`[추론]` 바인딩 확대	인용 17 → 19	역인덱스 표의 숫자
실행 모드 `이어서` 신설	모드 3 → 4종	전달부·`ptop-lead` 소비부 (둘 다 3종)
문서 1건당 producer 1기동	인스턴스 3 → 3N	`_progress.md` "3행" 초기화
검색식 함정 항목 추가	한계 2 → 3항	같은 문단의 리드 개수어 `알려진 한계 2가지`
표에 행 2개 추가	표가 2줄 아래로 밀림	그 표를 `파일:라인` 으로 가리키던 인용 (가리키는 범위가 어긋남)
Phase 2에 기동 축소 규칙 신설	기동 대상 3 → 3−N	Phase 3·4의 완료 알림 대기(생략된 에이전트는 알림을 안 보낸다)
원장에 `생략` 상태 신설	상태 3 → 4종	그 상태를 정의한 표(`data-protocol.md` 진행 원장) — 정의부에 없으면 기록 주체가 안 적는다

열거형에 값을 추가했으면 그 열거형을 정의한 표를 먼저 고친다. 6라운드 연속 같은 유형이 재발한 이유는 늘 쓰는 쪽(Phase 분기)만 고치고 정의부를 안 고쳤기 때문이다. 정의부에 없는 값은 기록 주체가 애초에 적지 않으므로 소비처가 아무리 정확해도 동작하지 않는다. 순서: ① 정의한 표 → ② 기록하는 곳 → ③ 읽는 곳 → ④ 위임했으면 수신처. 넷을 같은 편집에서 본다.

④ 위임의 수신처 확인. (Phase 3에서 판단)·(위 참조)·(§X 참조) 처럼 처리를 다른 곳으로 넘기는 문자열을 썼으면, 그 수신처를 열어 해당 분기가 실재하는지 확인한다. 위임은 소비처를 지정할 뿐 만들지 않는다 — 수신처가 없으면 그 규칙은 문서에만 있고 실행되지 않는다. 실제 사례: mode-rules.md 가 developer 생략을 "Phase 3에서 판단"으로 넘겼는데 Phase 3에 분기가 0건이라, 생략 으로 적어 둔 에이전트가 실제로 기동돼 원장이 거짓이 됐다.

앵커로 인용을 바꿀 때는 대상 파일에서 절 제목을 즉시 확인한다. 라인 번호를 앵커로 바꾸면 드리프트가 없어지지만, 앵커 자체를 잘못 적으면 같은 오류가 난다(실제로 §5 로 적었으나 대상 문장은 §6 이었다). ⚠ grep -n "^## " 만으로는 부족하다 — 하네스는 ### 소제목과 인용문 안의 굵은 소절 제목 (> **…**)도 앵커로 쓴다. 다음처럼 넓게 뜬 뒤 눈으로 고른다:
grep -nE "^#{2,4} |^> \*\*" <대상파일>
⑤ 어떤 주체를 금지·전담으로 지정했으면 그 주체의 정의 파일을 연다. 오케스트레이터 문서에만 "팀원은 하지 않는다"를 적고 에이전트 정의에 반대말이 남으면, 구속 대상이 그 금지문을 읽지 않는다. 실제 사례: _workspace_prev/ 이동을 "오케스트레이터 전담"으로 정해 놓고 ptop-lead·ubisam-analyst에 "전면이면 옮긴다"가 남아 이중 이동으로 병렬 산출물이 딸려갈 상태였다.

⑥ 절을 다른 파일로 옮겼으면 그 절 제목을 grep -rn 해 인용처를 전부 연다. 라인→앵커 전환은 라인 드리프트를 없애지만 절의 파일 이동은 앵커도 무력화한다. 실제 사례: 교차 확인 질문을 collection-rules.md로 옮긴 뒤 ptop-lead가 여전히 SKILL.md Phase 4를 지목해, 답할 주체가 지목된 곳을 열면 질문이 없었다.

⑦ 고친 문장의 형제를 함께 본다 — 참조 문서의 리드 문장(표는 고쳤는데 그 위 요약문이 옛말), 그리고 복붙 쌍둥이 파일(에이전트 정의 6종은 서로 문단을 복사해 쓴다). 한쪽만 고치면 세 줄 간격으로 자기모순이 남는다.

자주 재발하는 두 가지. ① 자기 문단이 스스로 개수를 선언하는 말(N가지·N종·N개·N건·N행)은 항목을 추가·삭제할 때 같은 편집에서 고친다. 항목 밑에 ①②③ 을 붙이는 순간 그 문단은 개수 소비처를 갖는다. ② 다른 파일을 파일:라인 으로 가리켜 놓고 그 파일을 늘리면 인용이 조용히 어긋난다. 같은 배치에서 A를 고치고 B가 A를 가리키면 B의 라인 번호를 다시 확인한다.

드리프트를 없애는 방법: 라인 번호 대신 앵커 문자열로 가리킨다. 05-form-schemas.md:78-85 대신 05-form-schemas.md §C 의 8탭 표 처럼 쓰면 파일이 늘어나도 인용이 살아 있다. 소스 코드(.cs)는 라인 번호가 유일한 수단이라 예외지만, 하네스 문서끼리는 앵커를 쓴다.

그래서 열거형 값·항목 수·인스턴스 수를 바꿨으면 반드시 소비처를 검색한다.

# 예: 옛 열거를 그대로 쓰는 곳이 남았는지 / 새 값의 소비처가 정말 있는지
grep -rn "초기/부분/전면" .claude
grep -rn "이어서" .claude

⚠ .claude/ 를 검색할 때는 하위 폴더를 직접 지정해야 한다 (실측 확인). .gitignore:39 의 .claude/* 때문에 ripgrep(= Grep 도구)이 .claude 를 통째로 건너뛴다.

검색 시작점 결과

저장소 루트 · .claude 0건 — 에러 없이 조용히 실패

.claude/agents · .claude/skills 정상

따라서 Grep 도구는 path: ".claude/skills" 처럼 하위를 지정해 두 번 돌리고, 셸을 쓸 때만 grep -rn ... .claude(bash grep은 무시 규칙을 안 본다)가 한 번에 된다. 이 절의 예시 명령이 Grep 도구가 아니라 Bash grep -rn 인 것은 그 때문이다 — 바꾸지 말 것.

.gitignore 의 negation 2줄은 git 추적만 되살리고 ripgrep 프루닝은 되살리지 못한다 (재현: rg --files .claude 는 1건(settings.json 뿐)이고 rg --files --no-ignore .claude 는 전체를 센다. rg --files .claude/skills 도 정상. 숫자는 파일이 늘면 변하므로 박제하지 말고 명령을 돌려 비교한다 — 판정 근거는 1 ≪ 전체 라는 관계다.)

_workspace/ 도 무시 대상이지만 경로를 명시하면 rg가 정상 탐색한다(rg --files _workspace = --no-ignore 와 동수). 즉 --no-ignore 가 필요한 것은 루트에서 glob 으로 훑을 때이며, .claude 는 경로를 명시해도 루트 시작점이면 프루닝된다 — 둘은 다른 증상이다.

검색 시작점	결과
저장소 루트 · `.claude`	0건 — 에러 없이 조용히 실패
`.claude/agents` · `.claude/skills`	정상

판정: 새 값이 정의부에만 있고 소비처가 0건이면 그 값은 동작하지 않는다. 단, 위 함정 때문에 0건을 보면 검색 시작점부터 의심한다 — 죽은 값과 못 찾은 값은 다르다. 개수를 문서에 적을 때는 그 개수의 진실원(표·파일 목록)과 같은 편집에서 함께 고친다.

규칙 ↔ 바인딩 역인덱스

rules.md 조항이 하네스에서 실제로 시행되는지 점검하는 표다. 조항을 추가하면 이 표도 갱신한다 — 바인딩 누락이 3라운드 연속 감사 지적으로 나온 패턴이라 자가 점검 수단을 둔다.

자가 점검 (조항별 인용 건수를 센다):

grep -rhoE "rules\.md.{0,20}" .claude docs CLAUDE.md \
  | grep -oE '#[0-9]+' | sort -t'#' -k2 -n | uniq -c

검색식 함정 2가지 (둘 다 실측 확인). ① 실제 표기는 `rules.md` #2 라 백틱이 사이에 낀다. rules\.md\s*# 로 찾으면 0건이 나온다. ② 뒤 범위를 .{0,3} 로 좁히면 #15·#16 같은 복합 인용에서 뒤 번호를 놓친다(#16이 1건으로 보임). 문자클래스로 ·(U+00B7)를 넣는 우회도 안 된다 — 멀티바이트라 grep -E 브래킷에서 깨진다. 그래서 뒤 20자를 통째로 떠서 #N을 전부 뽑는다. 0건·급감이 보이면 미바인딩이 아니라 검색식부터 의심한다 (rules.md #15). 알려진 한계 3가지: ① #11~13 은 #11 로만 집계된다(범위 표기). ② 앞 20자 안에 rules.md 가 없는 맨 #N 표기는 집계되지 않는다 — 그래서 바인딩할 때는 반드시 rules.md 를 함께 쓴다. ③ 위 명령이 Bash grep 인 것은 Grep 도구가 .claude 를 프루닝하기 때문이다(위 §소비처 확인 의무). 도구로 바꾸면 .claude 몫이 통째로 빠져 전 조항이 급감한다.

조항	요지	바인딩되어야 할 곳
#1	주석·이름 맹신 금지	분석 스킬 3종 (조항번호 인용 + 문장 반영 병행)
#2	수정은 승인받기	승인 게이트를 가진 전 스킬·에이전트
#3	한글 깨짐 방지	PTOP 에이전트 3인 + 산출 스크립트를 실행하는 스킬
#4	`.md` 200줄 상한	`.md` 산출물을 쓰는 에이전트 전원
#5	`@경로` 임포트	`rules.md` 자체 (하네스는 인용하지 않아도 된다)
#6	완료 후 `.md` 갱신 확인	두 오케스트레이터 + 산출물 스킬
#10	중간 진행 보고	두 오케스트레이터 + 분석 스킬
#11~13	출력 색상 규약	에이전트 전원 + 사용자에게 보고하는 스킬
#15·#16	추론 검증 · `[추론]` 표기	에이전트 전원 + 값·해석을 생성하는 스킬 (2026-08-03 신규)

이 표에 인용 건수를 적지 않는다. 세 라운드 연속으로 "바인딩을 늘리고 표의 숫자를 안 고쳐 표가 거짓이 되는" 회귀가 났다. 숫자가 필요하면 위 명령을 그때 실행한다 — 표는 어디에 있어야 하는가만 말하고, 몇 건인가는 명령이 답한다.

#7~9·#14는 세션 전역 규약이라 하네스가 개별 인용하지 않는다 — 미바인딩이 아니다. 조항이 표에 있는데 해당 위치에서 검색되지 않으면 그때가 미바인딩이다.

변경 이력

표가 60행을 넘어 별도 파일로 분리했다 (rules.md #4) → harness-ptop-changelog.md 하네스를 고쳤으면 그 파일에 행을 추가한다.

주의 1: .claude/agents/에 파일을 추가·이동했거나 CLAUDE.md·@ 임포트 대상 문서를 고쳤다면 세션을 재시작해야 반영된다. 에이전트는 Agent 도구에 등록되지 않고, CLAUDE.md는 세션 시작 시점의 판본이 계속 쓰인다 — 파일을 고쳐도 현재 세션의 라우팅 가드는 옛날 것이다. 디스크 내용과 실제 적용 내용이 다를 수 있다는 뜻이므로, 하네스를 고친 직후 검증할 때 주의한다.

주의 2: 에이전트 frontmatter에 tools:를 넣어 쓰기 도구를 막지 않았다. 여섯 에이전트 모두 각자의 작업공간(PTOP 3인 = 저장소 루트 _workspace/, Ubisam 3인 = docs/[Ubisam산출물]/_workspace/)에 .md 산출물을 직접 쓰기 때문이다. "분석 전용"은 소스 코드를 고치지 않는다는 뜻이며, 파일 쓰기 자체를 막으면 하네스가 아무 산출물도 만들지 못한다.

13 KiB Raw Blame History Unescape Escape