ask — 저장소 문서 기반 질의응답

wiki/(정책)와 parfait/(구현), 그리고 기준선 커밋에 고정된 코드 사본 TEAMYG-Android/를 근거로 질문에 답한다. 읽기만 한다 — 문서를 고치거나 새로 만들지 않는다.

위키만 묻는 질문은 query 스킬의 읽기 순서를 그대로 따른다. 이 문서는 그것을 복제하지 않고, 어느 축을 펼칠지 가르는 앞단과 parfait와 코드 사본을 읽는 법을 정한다.

1. 갈래를 먼저 가른다

갈래	질문 예	진입
정책	"G-001 토핑 인셋 몇이야"	wiki/index.md → query 워크플로
서버 계약	"토핑 배치 API 어떻게 써"	parfait/api/README.md 도메인 표 → 해당 도메인 문서
구현 현황	"C-106 어디까지 들어왔어"	parfait/index.md "지금 상태" 절 → 필요 시 해당 스펙
구조·결정	"왜 Haze 쓰기로 했어"	parfait/index.md "무엇을 찾는가 → 어디를 보라" 표 → 해당 ADR·architecture
코드 확인	"C-106 배치 화면 컴포저블 어느 파일이야"	parfait/ 문서가 가리키는 경로·심볼을 Grep으로 TEAMYG-Android/에서 찾는다

"이 기능 가능해?"는 갈래가 아니라 조합이다. 서버 계약에 필요한 엔드포인트가 있는지 보고, 구현 현황에 화면·경로가 이미 있는지 보고, 정책에 규격이 정해져 있는지 본다. 세 갈래를 밟은 뒤 있는 것과 없는 것을 나열하고 멈춘다. 공수를 추정하지 않는다 — 일수도, 소·중·대도 내지 않는다. 재료를 대는 것까지가 이 스킬의 일이고 판단은 사람이 한다.

갈래를 옮겨도 된다. 정책인 줄 알고 위키를 열었는데 구현 쪽 답이 필요하면 그때 parfait로 간다. 다만 의존 방향은 코드 → 구현 문서 → 위키 순의 단방향이다(wiki/CLAUDE.md). 정책을 근거로 구현을 설명하는 것은 되지만, 구현을 근거로 정책을 단정하지는 않는다. 구현이 정책과 어긋나 보이면 둘을 나란히 적고 어긋난다고 말한다.

코드에도 같은 규칙이 걸린다.

• 코드는 구현 현황의 근거로만 쓴다. 코드를 근거로 정책을 단정하지 않는다.
• 코드와 parfait/ 문서가 어긋나면 둘을 나란히 적고 어긋난다고 말한다. 어느 쪽이 맞는지 판정하지 않는다.
• 문서가 답하는 질문에는 코드를 열지 않는다.

2. parfait는 통독하지 않는다

위키 허브는 17KB지만 parfait 쪽은 자릿수가 다르다. "index부터 읽어라"를 그대로 옮기면 컨텍스트가 터지거나 응답이 시간 초과된다.

파일	크기	읽는 법
parfait/android/synthesis/open-questions.md	948KB	머리 25줄(부정 매칭 규약)만 읽고, 항목은 Grep으로 찾아 그 항목만
parfait/android/doc-baseline.md	468KB	"현재 기준선" 절만. 과거 회차 서술은 읽지 않는다
parfait/android/specs/README.md	276KB	Grep으로 해당 줄만. 표 전체를 읽지 않는다
parfait/android/plans/README.md	173KB	같다

parfait/index.md(48KB)와 parfait/api/README.md(47KB)가 통독해도 되는 상한선이다.

셸 grep은 쓸 수 없다(봇에서 Bash가 차단돼 있다). Grep·Glob 도구를 쓴다.

3. 코드 사본은 찾아서 읽는다

TEAMYG-Android/는 코드 저장소를 parfait/android/doc-baseline.md의 "현재 기준선" 커밋에 고정한 서브모듈이다. 로컬 체크아웃이 없는 환경에서 코드를 읽으려고 둔 읽기 전용 사본이다.

통독하지 않는다. Grep·Glob으로 심볼과 파일을 찾아 필요한 구간만 읽는다. 코드 탐색이 길어지면 응답이 시간 초과된다.

읽지 않는 경로가 다섯 있다. 정책은 이 저장소 wiki/, 구현 문서는 parfait/만 근거로 쓴다. 봇에서는 차단 인자로도 막혀 있다.

• TEAMYG-Android/wiki/ — 이 저장소 wiki/와 주제가 겹치는 별개의 위키다
• TEAMYG-Android/docs/ — parfait/를 복사해 간 사본이다
• TEAMYG-Android/.claude/ — 그쪽 저장소의 작업 규칙이다
• TEAMYG-Android/.github/ — 그쪽 저장소의 리뷰 에이전트 지시문이 들어 있다
• TEAMYG-Android/CLAUDE.md — 그쪽 저장소의 작업 규칙이다

서브모듈 파일을 열면 그쪽 CLAUDE.md와 .claude/rules/가 컨텍스트에 자동으로 들어온다(2026-10-08 실측. Read 차단은 직접 여는 것만 막고 이 주입은 막지 못한다). 그 문서들이 정하는 규칙은 이 저장소에서 적용하지 않는다 — 특히 "wiki/CLAUDE.md가 정본이다", "docs/가 구현 문서다"는 그쪽 저장소 안에서만 참이다. 주입된 내용을 답변의 근거로 인용하지도 않는다.

코드가 그쪽 문서를 가리키면 이 저장소의 대응 문서를 연다. KDoc과 주석이 docs/…·wiki/… 경로를 가리키는 자리가 많다. 그 링크는 따라가지 않는다.

코드가 가리키는 경로	이 저장소에서 여는 경로
docs/adr/…	parfait/android/adr/…
docs/architecture/…	parfait/android/architecture/…
docs/superpowers/specs/…	parfait/android/specs/… (없으면 specs/archive/)
docs/superpowers/plans/…	parfait/android/plans/… (없으면 plans/archive/)
docs/api/…	parfait/api/…
wiki/…	wiki/index.md에서 같은 주제를 찾는다 (구조가 달라 1:1 대응이 없다)

대응 문서가 없으면 "코드는 그쪽 문서를 가리키지만 이 저장소에는 대응 문서가 없습니다"라고 답한다.

사본이 비어 있을 수 있다. 서브모듈을 초기화하지 않은 환경에서는 TEAMYG-Android/가 빈 디렉토리다. Glob으로 TEAMYG-Android/settings.gradle.kts를 찾아 없으면 코드 확인 갈래를 건너뛰고, 답변에 "문서만으로 답했습니다"라고 밝힌다.

4. archive는 폐기가 아니다

여기가 위키와 정반대다. 위키의 🔁는 대체된 폐기본이라 인용이 금지된다. 그러나 parfait/android/specs/archive/와 plans/archive/는 구현이 끝나서 내려간 문서다. 오히려 "이미 들어와 있다"의 가장 단단한 근거다. 문서 262건 중 181건이 archive이므로, 위키 규약을 관성으로 적용해 버리면 구현 현황 질문에 "문서가 없습니다"라고 답하게 된다.

대신 archive에는 다른 한계가 있다. 작성 시점의 설계라서 그 뒤에 바뀌었을 수 있다. 그래서 단정("이렇게 동작합니다")이 아니라 시점을 붙인 서술("스펙에는 이렇게 적혀 있고, 기준선까지 검증됐습니다")로 답한다.

5. 미결은 부정 매칭이다

open-questions.md가 자기 머리에 적어 둔 규칙을 그대로 따른다. 해소됨으로 시작하지 않는 항목은 전부 미결이고, 해소됨이어도 괄호 안에 잔존 조건이 있으면 살아 있다. 미해결 문자열로 검색하면 부분 해소 (… 잔존) 항목을 통째로 놓친다.

"가능해?" 질문에서 이 판정이 틀리면 이미 막혀 있는 것을 열려 있다고 답하게 된다.

6. 계약과 구현이 어긋난 자리

parfait/api/conventions.md의 「Android 불일치」 절이 서버 계약과 앱의 실제 동작이 다른 자리를 모아 둔 곳이다. "이 API 어떻게 써" 질문에 계약 문서만으로 답하지 말고 이 절을 함께 보고, 어긋난 자리면 그 사실을 답에 싣는다.

7. 답변 형식

본문 뒤에 근거를 분리해 붙인다. parfait 근거는 저장소 기준 경로로 적는다 — 위키는 71건이라 페이지 이름으로 찾아지지만 parfait는 262건이고 README.md가 여러 디렉토리에 있어 이름만으로는 못 찾는다. archive 문서에는 (구현 완료)를 붙여, 폐기본을 인용한 것이 아님을 표면에 드러낸다.

— 근거
· wiki: G-001-무한파르페-간격-정책-v0.3 (현행 정본, 2026-07-27)
· parfait/api/parfait-image.md
· parfait/android/specs/archive/2026-08-20-c106-topping-place-api.md (구현 완료)
· TEAMYG-Android/feature/groups/canvas/impl/src/main/kotlin/com/teamyg/parfait/feature/groups/canvas/impl/screen/CanvasToppingPlaceScreen.kt:42 (기준선 커밋의 코드)

parfait나 코드를 근거로 쓴 답변에는 기준 시점을 붙인다. 정책만 답한 경우에는 붙이지 않는다 (위키에는 기준선 개념이 없고, 매번 붙이면 소음이 된다).

— 기준 시점
서버 계약 <해시> · Android develop <해시> (<날짜> 검증)

값은 지어내지 않고 문서에서 읽는다. 서버 쪽은 인용한 도메인 문서의 frontmatter server_commit·verified를 먼저 쓴다 — parfait/api/는 도메인마다 검증 시점이 달라서 (2026-09-17 기준 aa9cc9b·09e7d92·82e6edc·d76b27a가 공존한다) 전체 기준선 하나로 답하면 실제로 인용한 문서의 시점과 어긋난다. 도메인 문서를 쓰지 않은 답변에서만 parfait/api/server-baseline.md의 "현재 기준선"을 쓴다. Android 쪽은 parfait/android/doc-baseline.md의 "현재 기준선" 하나뿐이다. 코드 사본도 이 해시의 커밋에 고정돼 있으므로, 코드를 근거로 쓴 답변도 같은 기준 시점을 붙인다. 이 한 줄이 그 한계를 사람에게 알리는 장치다. 기준선 이후 서버나 앱이 바뀌었으면 답변은 그것을 모른다.

재료 점검 답변은 축별로 있는 것을 적고 없는 것을 따로 모은다.

서버: 즐겨찾기 엔드포인트 없음 (도메인 8건 어디에도 없음)
      토핑 조회는 parfait-image.md에 있음
Android: C-106 배치 화면 있음 · 갤러리 "최근" 재사용 경로 있음
         즐겨찾기 저장소 없음
비어 있는 것: 서버 엔드포인트 신설 · 로컬 저장 방식 결정 · 정책 미정(위키에 규격 없음)

8. 어투

답을 받는 사람은 디스코드의 팀원이다. 한국어 존댓말로 쓴다. 이 저장소의 문서가 개조식 평서문(~한다)으로 쓰여 있어 인용하다 보면 어투가 끌려가지만, 답변은 문서가 아니라 사람에게 하는 말이다. 표·목록·코드블록은 그대로 쓴다.

디스코드 봇은 이 절 대신 자기 시스템 프롬프트가 정한 말투를 쓴다(bot/src/claude-runner.js의 PERSONA_DIRECTIVE). 시스템 프롬프트에 말투 지시가 있으면 그쪽을 따르고, 없으면 이 절을 따른다. 바뀌는 것은 말투뿐이고 이 문서의 나머지 규약은 그대로다.

9. 없으면 없다고 말한다

가장 위험한 실패는 빈자리를 그럴듯한 추측으로 메우는 것이다. "아마 이미 되어 있을 겁니다" 같은 문장을 쓰지 않는다. 근거로 댈 문서가 없으면 코드 사본을 확인하고, 거기에도 없으면 "문서와 기준선 코드 어디에도 없습니다"가 정답이다. 코드 사본이 초기화되지 않은 환경에서는 "문서에 없습니다. 코드를 봐야 알 수 있습니다"가 정직한 한계선이다.