GoldTime은 스크린타임 한도를 넘기면 Shield 흐름과 보상형 광고 해제를 통해 사용 시간을 의식하게 만드는 iOS 앱입니다. 메인 SwiftUI 앱 1개 + Screen Time extension 3개, Clean Architecture 5개 레이어(폴더링)로 구성됩니다.
이 파일은 항상 로드되는 진입점입니다. 세부 규칙은 여기 담지 않고, 작업 위치에 따라
자동으로 로드되는 nested 가이드와 "찾아 읽는 공통 문서"로 분리했습니다.
AGENTS.md는 이 파일의 사본입니다(편집은 CLAUDE.md만, 동기화는 scripts/sync-agent-docs.sh).
- 의존 방향은 단방향:
App → Presentation → Domain ← Data → Core. 역방향 import 금지. Domain/Data에서@Observable·@Published금지. Presentation에서 집행 로직(ScreenTimeManager호출, 잠금/모니터링 상태 변경)은 UseCase로만 — SharedStore 값 읽기 등 허용 경계는Presentation/CLAUDE.md에 정의. - 공유 상태(
SharedStore, App Group)는 하위 호환 우선. key 이름·Codable 구조 변경은 설치된 앱 상태 마이그레이션이다. 새ScreenTimeGroup필드는 custom Codable로 throw하지 않게 디코딩한다(배열 전체try?디코딩 → 1개 실패가 전체 소실). - Screen Time / Shield / FamilyControls / DeviceActivity / AdMob 실제 표시는 실기기 검증 필수. 시뮬레이터 build는 컴파일 회귀만 증명하지 런타임 동작을 증명하지 않는다.
- 새 색상은 Asset Color. RGB/hex literal과
Color+Brand.swift같은 수동 색상 extension은 금지(AccentColor는Color.accent자동 생성). .xcodeproj, entitlements, App Group,SharedStore,ScreenTimeManager, extension은 위험도 High → 직렬로 처리하고 검증 메모를 남긴다. 워크트리의 사용자 변경은 보존한다.- 커밋
[Type] 한글 설명. 광고 관련 변경은[Ad]태그. 브랜치는 스스로 만들지 않는다 —main포함 현재 브랜치에서 그대로 작업하고, 분리가 필요하면 사용자가 요청한다.
레이어/타겟 폴더에 CLAUDE.md가 co-locate 되어 있다. 그 경로의 파일을 열면 해당
CLAUDE.md가 자동으로 함께 로드된다 → 필요한 문서만 정확히 읽힌다.
CLAUDE.md ← 항상 (이 파일)
GoldTime/GoldTime/App/CLAUDE.md ← 진입점/DI 패턴(생성자 기본값 주입)
GoldTime/GoldTime/Core/CLAUDE.md ← SharedStore/ScreenTime 함정 (High)
GoldTime/GoldTime/Domain/CLAUDE.md ← import/UseCase/Repository 규칙
GoldTime/GoldTime/Data/CLAUDE.md ← Repository 구현/타입 매핑
GoldTime/GoldTime/Presentation/CLAUDE.md ← ViewModel/컴포넌트/색상
GoldTime/DeviceActivityMonitorExtension/CLAUDE.md ← 콜백/일일 리셋/시간대 (High)
GoldTime/ShieldConfigurationExtension/CLAUDE.md ← Shield UI 읽기 계약 (High)
GoldTime/ShieldActionExtension/CLAUDE.md ← Shield 액션 쓰기 계약 (High)
예: Core/Persistence/SharedStore.swift를 만지면 이 파일 + Core/CLAUDE.md가 함께 로드된다.
→ 다른 레이어 문서를 일부러 찾아 읽지 말 것. 작업 위치가 필요한 문서를 알아서 가져온다.
작업 중 함정을 발견하면 가장 가까운 CLAUDE.md의 "주의사항" 절에 누적한다(/learn).
| 문서 | 언제 |
|---|---|
| docs/agent/architecture.md | 레이어 의존 방향, 새 파일 배치, UseCase/Repository 추가 |
| docs/agent/critical-flows.md | Screen Time/Shield/광고/App Group 런타임 흐름 전체 |
| docs/agent/testing.md | 실기기 검증 시나리오, regression 기준 |
| docs/agent/working-rules.md | 위험도, 검증 명령(xcodebuild)·함정, 실기기 OSLog 수집 |
| docs/agent/definition-of-done.md | 작업 종료 규칙 (완료 직전 자가 점검) |
| docs/agent/decision-context.md | 제품 범위, 하지 않을 일, ADR |
| docs/agent/product-context.md | 문구, 톤앤매너, 화면 감정 |
| docs/agent/ui-design-system.md | iOS UI/HIG, 공용 컴포넌트, Asset Color |
| docs/agent/competitive-research.md | 기획 모호성, 경쟁 앱 참고, GoldTime다움 |
| docs/agent/analytics.md | Firebase/GA4 이벤트·코호트·대시보드/BigQuery 해석 |
| docs/agent/app-icon-brief.md | 앱 아이콘 시안/프롬프트 |
| docs/agent/project-map.md | 타겟/경로/entitlement/App Group 위치 |
기획이 모호하면 경쟁 앱을 그대로 따르지 말고 GoldTime의 비용감·마찰·Shield 선택 경험에 맞게
해석한다. 문서가 코드와 다르면 코드가 진실 — 발견 즉시 가장 가까운 CLAUDE.md를 고친다.
루트 TODO.md가 "하던 일 / 다음 할 일 / 실기기 검증 대기"의 단일 출처다.
세션 시작·복귀 시 먼저 확인하고, 작업 시작·완료 시 갱신한다(완료 항목은 지운다 —
기록은 git log 담당). 완료 보고에 남기는 실기기 체크리스트는 TODO.md의 "실기기 검증
대기"에도 기록한다. 실기기 검증 세션은 /device-verify, 커밋 전 도메인 리뷰는
gt-reviewer 에이전트를 쓴다.
완료를 보고하기 전에 docs/agent/definition-of-done.md로
자가 점검한다. 핵심: 의존 방향/상태 규칙 위반 없음, 변경에 가장 가까운 CLAUDE.md 갱신,
정한 검증 실행, 실기기로만 확인 가능한 항목은 완료 보고에 사용자 체크리스트로 남김.
빌드/테스트는 xcodebuild CLI를 기본으로 쓴다(Xcode MCP 툴은 CLI가 막히거나 IDE 상태가
필요할 때만 fallback). 기본형:
xcodebuild -project GoldTime/GoldTime.xcodeproj -scheme GoldTime -destination 'platform=iOS Simulator,name=iPhone 17 Pro' -quiet build(테스트는 build→test).
특정 테스트 식별자는 괄호 포함(-only-testing:'GoldTimeTests/Suite/이름()'), 0매칭이면
TEST SUCCEEDED로 뜨는 거짓 성공 함정이 있어 xcresult로 개수를 확인한다. 자세히는
docs/agent/working-rules.md의 "검증 명령".