designer/technical-writer 가드레일: 심볼 실재 확인 없음 + 문서 갱신 시 내용 유실

한 세션에서 `designer` 와 `technical-writer` 가 각각 다른 방식으로 잘못된 문서를 만들었다. 두 실패의 원인이 달라서 함께 적는다. `#24 (draft) Designer update` 와 인접하지만 같은 항목은 아니다. --- ## A. designer — 인용한 코드 심볼이 실재하는지 확인하지 않는다 `designer.md` 의 Input 에 `Existing codebase context` 가 있지만, Instructions 어디에도 **인용한 심볼이 실제로 존재하는지 확인하라**는 단계가 없다. 결과적으로 「그 프레임워크에서 흔한 이름」을 지어낸다. 한 번의 design 실행에서 나온 것들 (Django 프로젝트): | PLAN 이 인용한 것 | 실제 | |---|---| | `school/enums/` 패키지에 enum 을 둔다 | 그 패키지가 없다. 이 앱은 enum 을 엔티티 모듈 안 `TextChoices` 로 둔다 | | `IsInternalAdmin` 권한 클래스 | 존재하지 않는다. 실제로는 `IsStaff` | | `api.settings.local_test_docker_replicated` | 존재하지 않는 settings 모듈 | | `notification/service/InfobankAlimtalkService.py` | 실제 경로는 `api/common_service/` | 전부 **관례상 그럴듯한 이름**이라는 공통점이 있다. `school/enums/` 는 Django 에서 흔한 레이아웃이고, `IsInternalAdmin` 은 DRF 권한 클래스 작명 관례에 맞는다. 즉 리포를 읽고 쓴 게 아니라 **사전지식으로 채웠다.** 위험한 건 이게 조용히 통과한다는 점이다. `IsInternalAdmin` 을 그대로 구현하려던 Coder 가 대체재로 `IsAdmin` 을 골랐다면, 그건 이 프로젝트에서 **학원 관리자 플래그**라 「내부 전용」 엔드포인트가 외부에 열렸을 것이다. 문서 리뷰에서 이름만 보면 맞아 보인다. ### 제안 `designer.md` Instructions 에 검증 단계를 추가: ``` ### N. Codebase Verification (Required) Before citing any code symbol (file path, class, function, setting module) in a PLAN, verify it exists in the working tree. - Do not cite a symbol you have not confirmed. - If a plan requires a symbol that does not exist yet, mark it explicitly as NEW rather than citing it as existing. - Framework conventions are not evidence. Read the repository. ``` `spec-validator` 에 같은 축을 넣으면 사후에도 잡힌다. 실제로 이번에 validator 프롬프트에 「인용한 심볼의 실재를 전수 확인하라」를 넣었더니 위 4건이 그 축에서만 걸러졌다. --- ## B. technical-writer — 기존 문서 갱신 시 내용을 보존하지 않는다 이미 작성된 PLAN/TEST 를 **갱신**하라고 했더니 요약 재작성을 했다. | 파일 | 전 | 후 | |---|---|---| | `PHASE_5_PLAN_*.md` | 18,244 B | 4,319 B | | `PHASE_3_PLAN_*.md` | 13,731 B | 6,563 B | 사라진 것 — 대상 산출 로직, 배치 발송 설계, 엔드포인트 2개, 마이그레이션 2건. 더 나쁜 건 **빈칸을 사전지식으로 메운** 것이다. 새로 들어간 서술 셋이 전부 「그 프로젝트에서 보통 그렇게 하는 방식」이었고 전부 틀렸다. - 실제로는 A 클라이언트를 직접 호출하는데 「B 큐를 통해 호출」로 적음 (B 는 이 리포의 다른 경로에서 쓰는 흔한 방식) - 원 설계가 **자동 재시도 없음**을 명시적 결정으로 적어뒀는데 「SQS visibility timeout 이 재시도를 처리한다」로 뒤집음 - 요청 단위로 잡아야 하는 멱등키를 수신자 단위로 적음 → 그대로 구현하면 배치 발송이 불가능해진다 `technical-writer.md` 에는 `Do NOT write modified code directly` 같은 규칙은 있지만 **기존 문서를 고칠 때 무엇을 보존해야 하는지**에 대한 규칙이 없다. ### 제안 `technical-writer.md` 에 갱신 규칙 추가: ``` ### Updating Existing Documents When the task is to UPDATE an existing document: - Apply the delta. Do not regenerate the document from scratch. - Preserve sections the delta does not touch, verbatim. - If a section must be removed, say why in the report. - A significant size reduction is a signal you rewrote instead of edited. Re-read the original and redo the edit. - Never fill a gap with what the framework "usually" does. If the source does not say, write "not specified in SPEC". ``` --- ## C. 오케스트레이션 쪽 관찰 두 실패의 성격이 달랐다. - **designer** 는 입력이 작았는데도(SPEC 1,169줄) 틀렸다 → 스코프 문제가 아니라 **검증 규율** 문제 - **technical-writer** 는 SPEC 99KB + 대상 파일 10개 + 변경 14건을 한 번에 받았다 → **과부하**. 편집을 포기하고 요약으로 전환한 것이 그 징후 후자는 phase 당 에이전트 1개로 쪼개고 **필요한 SPEC 절만** 주면 완화된다. `commands/design.md`·`update-docs.md` 가 「문서 여러 개를 한 에이전트에 맡기지 말 것」을 권고하면 좋겠다. --- ## 부수 제안 — 문서 백업 `{working_directory}` 가 보통 git 제외라, 에이전트가 문서를 망가뜨렸을 때 **diff 도 revert 도 없다.** 이번에 상세 PLAN 을 그대로 잃었다. 에이전트에 문서 수정을 맡기기 전에 스냅샷을 뜨거나, `{working_directory}` 를 별도 git repo 로 관리하는 옵션이 있으면 좋겠다. ## 환경 - dotclaude 0.5.0