proto-socket/agent-task/proto_restructure/CODE_REVIEW.md

Code Review Reference - PROTO_MOVE

개요

date=2026-04-25 task=proto_restructure, plan=0, tag=PROTO_MOVE

이 파일을 읽는 리뷰 에이전트에게

각 항목의 구현을 실제 소스 파일과 대조하고, 검증 결과 섹션의 출력이 코드와 일치하는지 확인하세요. 리뷰 완료 후 반드시 아래 순서로 아카이브하세요.

1. CODE_REVIEW.md → code_review_0.log (기존 code_review_*.log 수 = 0)
2. PLAN.md → plan_0.log (기존 plan_*.log 수 = 0)
3. PASS인 경우 complete.log 작성 후 종료. WARN/FAIL인 경우 새 PLAN.md + CODE_REVIEW.md 스텁 작성.

---

구현 항목별 완료 여부

항목	완료 여부
[PROTO_MOVE-1] proto/ 디렉터리 생성 및 generate_proto.sh 수정	[x]
[PROTO_MOVE-2] check_proto_sync.sh canonical 경로 변경	[x]
[PROTO_MOVE-3] PROTOCOL.md Proto Source 섹션 업데이트	[x]
[PROTO_MOVE-4] dart/lib/src/packets/message_common.proto 제거	[x]

계획 대비 변경 사항

• README.md, PORTING_GUIDE.md, typescript/README.md에도 이전 canonical 경로(dart/lib/src/packets/message_common.proto)가 남아 있어 함께 갱신했다. proto 원본 이동 후 사용자-facing 안내가 서로 충돌하지 않도록 하기 위한 변경이다.
• agent-ops/rules/project/**와 새 언어 템플릿에도 이전 proto 원본 경로가 남아 있어, 실제 구조와 다음 작업 지시가 어긋나지 않도록 protocol/dart 규칙 및 템플릿 문구를 함께 갱신했다.
• tools/generate_proto.sh 검증을 위해 로컬 PATH에 protoc-gen-dart와 임시 Go toolchain/protoc-gen-go를 추가해 실행했다. 스키마가 바뀐 것은 아니므로 생성 산출물(*.pb.dart, *.pb.go)은 최종 diff에 남기지 않았다.

주요 설계 결정

• proto/message_common.proto를 언어 옵션 없는 canonical proto로 둔다.
• Go/Kotlin의 proto copy는 기존처럼 언어별 generator option만 보존한다.
• Dart 생성은 --proto_path="$repo_root/proto"와 절대 출력 경로를 사용해 repo root의 proto를 입력으로 삼는다.
• check_proto_sync.sh는 canonical_proto를 기준으로 Go/Kotlin copy를 normalize 비교하고, 오류 메시지에서 "Dart canonical" 표현을 제거한다.

리뷰어를 위한 체크포인트

• proto/message_common.proto 존재 여부, 내용이 기존 Dart canonical과 일치하는지
• tools/generate_proto.sh — Dart 생성이 proto/ 입력, dart/lib/src/packets/ 출력으로 변경됐는지
• tools/check_proto_sync.sh — canonical_proto 변수가 proto/message_common.proto 참조하는지, "Dart canonical" 문구 제거됐는지
• PROTOCOL.md — "Proto Source" 섹션이 proto/message_common.proto를 canonical로 명시하는지
• dart/lib/src/packets/message_common.proto 파일이 삭제됐는지
• dart/lib/src/packets/ 에 .pb.dart 생성 결과물은 여전히 존재하는지
• tools/check_proto_sync.sh 실행 시 "Proto schemas are in sync." 출력되는지
• Dart/Go/Kotlin 테스트 모두 통과하는지

검증 결과

구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다.

PROTO_MOVE-1 중간 검증

$ ls proto/
message_common.proto

$ PATH="$HOME/.pub-cache/bin:/tmp/codex-gopath/bin:/tmp/codex-go/go/bin:$PATH" GOPATH=/tmp/codex-gopath tools/generate_proto.sh
Proto schemas are in sync.

$ cd dart && dart analyze
Analyzing dart...
No issues found!

PROTO_MOVE-2 중간 검증

$ tools/check_proto_sync.sh
Proto schemas are in sync.

PROTO_MOVE-3 중간 검증

$ grep "canonical" PROTOCOL.md
`proto/message_common.proto` is the canonical packet definition.

$ grep "dart/lib/src/packets/message_common.proto" PROTOCOL.md
(no output)

PROTO_MOVE-4 중간 검증

$ ls dart/lib/src/packets/
message_common.pb.dart
message_common.pbenum.dart
message_common.pbjson.dart
message_common.pbserver.dart

$ cd dart && dart analyze
Analyzing dart...
No issues found!

$ cd dart && dart test
00:15 +43: All tests passed!

최종 검증

$ tools/check_proto_sync.sh
Proto schemas are in sync.

$ rg -n "Dart canonical|canonical Dart|dart/lib/src/packets/message_common\.proto" --glob '!agent-task/**'
(no output)

$ cd dart && dart analyze
Analyzing dart...
No issues found!

$ cd dart && dart test
00:15 +43: All tests passed!

$ cd go && PATH="/tmp/codex-go/go/bin:$PATH" GOPATH=/tmp/codex-gopath go build ./...
(no output; exit 0)

$ cd kotlin && env JAVA_HOME=... ./gradlew build
BUILD SUCCESSFUL in 15s