소스 전수 조사 · 검증 체계 제안 · 워크플로우 도식 - #21
Merged
Merged
Conversation
소스 전체(106파일 13,964줄)를 네 갈래로 나눠 조사하고, 그 결과로 앞으로의 논의에 쓸 문서를 만들었다. 조사는 서브에이전트 넷을 병렬로 돌렸고 54만 토큰을 썼는데 요약만 돌아왔다 — 직접 읽었으면 그게 전부 본 컨텍스트에 쌓였을 것이다. 새 문서 - docs/architecture/CURRENT.md — 지금 구조. 레이어별 현황, 결합이 센 다섯 곳, 품질 기준선 13개. 가장 중요한 사실은 "테스트를 쓸 수 있는 코드와 없는 코드가 이미 폴더로 갈려 있다"는 것 (테스트 타깃이 Shared/만 컴파일한다) - docs/architecture/PATTERNS.md — 쓸 수 있는 설계 13가지를 장단점·비용·되돌리기 난이도·적합도로 비교. 결정은 안 했다 - docs/verification.md — 검증을 넷으로 나누자는 제안(기능·계약·환경·품질)과 "테스트 코드만으로는 왜 부족한가". v1.3.0에서 잡힌 버그 넷 중 테스트로 잡을 수 있었던 것이 0개다 - docs/review-criteria.md — 사람이 봐야 하는 코드와 안 봐도 되는 코드. 두 축은 "기계가 말해주나"와 "되돌리기 쉬운가" - docs/workflow.md — 프롬프트 하나가 어떤 순서로 도는지 도식 + 단계별 근거, 그리고 근거가 없는 칸 여섯 개 새 도구 (초안이지만 실제로 돈다) - tools/quality_baseline.py — 품질 기준선을 센다. 리팩터링 전후 비교용 - tools/artifact_check.sh — entitlements·plist·앱과 위젯 버전 일치 검사. v1.3.0의 버그 두 개를 이것 하나가 잡았을 것이다 - .claude/agents/ — surveyor·test-author 정의와 근거. 쓸지는 아직 안 정했다 규칙 - R1 확장: 고친 뒤 증상이 똑같으면 다음 가설 전에 그 코드가 도는지부터 확인한다 - R2 단서: 예외를 썼으면 무엇을 얻었는지 PR에 적는다 - R9 개정: 조사·감사·전수 훑기는 묻지 않고 위임한다. "사용자 요청 시에만"이 규칙의 실행 자체를 막고 있었다 (M14가 3버전 연속 0%) - R11 신설: 진단용 코드는 // TEMP: 표식을 달고 커밋 전에 걷는다 문서 모순 정리 — 테스트 개수(108→112), README의 CI 설명(Catalyst 누락), report 스킬의 낡은 R9 기록 자리, RELEASING의 PATCH 절 이름, BACKLOG의 TEST_HOST 오기와 이미 해소된 수출 규정 항목. Swift 코드는 한 줄도 안 바꿨다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
위험이 낮은 것부터 다섯 단계로 나눴다. 1단계는 코드를 한 줄도 안 옮기고 이미 Shared/에 있는데 테스트가 없는 아홉 개에 테스트만 붙이는 것이다 — 위험이 0이고, 그것만으로 다음 단계가 훨씬 안전해진다. 지표 정의에 M16·M17·M18을 추가하고, 고쳐야 하는 정의 넷(M15·M6·M11·M4)을 표로 적었다. 넷 다 v1.3.0에서 "지표가 규칙과 다른 것을 본다"가 드러난 것들이다. 백로그에 권한 파일 정리를 넣었다 — AI가 자기 권한 파일을 못 고치므로 사람이 해야 하는 항목이다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-22 요청이다. 이 프로젝트의 문서는 남에게 보여주는 산출물이 아니라 다음 세션의 사람과 AI가 읽는 것이다. 한 번 읽고 이해가 안 되면 안 읽히고, 안 읽히는 규범은 규칙으로 작동하지 않는다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
조사 결과를 읽고 고를 수 있게 한 장으로 정리했다. 세 부분이다 — 알고 있어야 하는 것(결정이 아닌 사실), 결정해야 하는 것 여섯, 지금은 안 정해도 되는 것. 결정마다 선택지·장단점·권고·언제 정해야 하는지를 붙였고, 아무것도 안 했을 때 무엇이 쌓이는지도 적었다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
변경 사항
Swift 코드는 한 줄도 안 바꿨습니다. 소스 전체를 훑고, 앞으로 리팩터링을 논의할 때 쓸 문서를 만들고, 규칙을 넷 손봤습니다.
조사는 서브에이전트 넷을 병렬로 돌렸습니다(사용자 허가). 넷이 54만 토큰을 쓰고 요약만 돌려줬습니다 — 직접 읽었으면 그게 전부 본 컨텍스트에 쌓여서 이후 모든 턴이 다시 읽었을 겁니다. R9가 세 버전 연속 0%였던 이유와 그 해법이 여기 있습니다.
새 문서
docs/architecture/CURRENT.mddocs/architecture/PATTERNS.mddocs/verification.mddocs/review-criteria.mddocs/workflow.md조사에서 나온 것 중 가장 중요한 사실 하나를 적으면 이겁니다. 테스트를 쓸 수 있는 코드와 없는 코드가 이미 폴더로 갈려 있습니다 — 테스트 타깃이
Shared/만 컴파일하기 때문입니다. 그래서 어떤 패턴을 고르든 "테스트하려면Shared/로 내려야 한다"가 먼저입니다. 새 레이어 이름을 붙일 필요가 없습니다.새 도구 (초안이지만 실제로 돕니다)
tools/quality_baseline.py— 품질 기준선을 센다. 리팩터링 전후 비교용tools/artifact_check.sh— entitlements·plist·앱과 위젯 버전 일치 검사두 번째 것은 v1.3.0에서 사람이 잡은 버그 두 개를 커밋 시점에 잡았을 도구입니다.
규칙 변경
// TEMP:표식 달고 커밋 전에 걷는다문서 모순 정리
조사가 찾아낸 것들입니다. 테스트 개수(108 → 112), README의 CI 설명(Catalyst 누락), report 스킬의 낡은 R9 기록 자리, RELEASING의 PATCH 절 이름, BACKLOG의
TEST_HOST오기와 이미 해소된 수출 규정 항목.스크린샷 / 영상
UI 변경 없음.
체크리스트
tools/quality_baseline.py로// TEMP:0건 확인확인한 것
artifact_check.sh는 서명된 Catalyst 산출물까지 검사해 통과했습니다.[x]로 고쳤습니다.위임했으면 쌌을 곳
이번엔 실제로 위임했습니다. 네 갈래(Features / Shared / Common·위젯 / 워크플로우·하네스)로 나눠 병렬로 돌렸고, 실측은
.claude/agents/README.md에 적었습니다.다음에 더 위임할 만한 곳: 문서 모순 찾기. 이번엔 워크플로우 조사에 얹어서 했는데, 그것만 따로 도는 감사 에이전트가 있으면 매 릴리스에 돌릴 수 있습니다.
관련 이슈
없음 (V1.3.0 후속)