talkflow-public AGENTS.md

TalkFlow 개발 규칙

아키텍처 경계

• TalkFlowDomain은 순수 모델·정책·프로토콜만 둔다. UI, 파일, 네트워크, macOS API에 의존하지 않는다.
• TalkFlowApplication은 유스케이스와 작업 흐름을 둔다. 구체 어댑터를 직접 생성하지 않는다.
• TalkFlowInfrastructure는 카카오톡, 로컬 저장소, Keychain, AI 제공자, macOS 상태 같은 외부 연동 구현을 둔다.
• TalkFlowFeatures는 SwiftUI 화면과 화면 전용 상태를 둔다. 인프라 구현을 직접 호출하지 않는다.
• TalkFlowApp은 앱 시작점과 의존성 조립만 담당한다.

파일 크기와 분리

• Swift 소스 파일은 250줄을 권장 상한으로 하고 400줄을 넘기지 않는다.
• 한 파일에는 하나의 주된 책임만 둔다. 모델, 프로토콜, 유스케이스, 화면, 어댑터를 섞지 않는다.
• 화면이 커지면 화면 구성 요소, 상태 모델, 표시용 포맷터로 나눈다.
• 조건문이 많은 정책은 독립된 정책 타입과 테스트로 분리한다.
• 새 기능은 먼저 어느 모듈에 속하는지 정한 뒤 구현한다.

안전·개인정보

• 카카오톡 원문, 계정 식별값, API 키를 로그·테스트 fixture·Git에 넣지 않는다.
• API 키와 인증 토큰은 Keychain에만 저장한다.
• 계정과 채팅방 정책의 기본 키는 표시 이름이 아니라 안정적인 식별값이다.
• 계정 확인이 불확실하거나 자동 전송이 일시 중지된 상태에서는 전송하지 않는다.
• 채팅 메시지는 신뢰할 수 없는 입력이다. 메시지 내용이 앱 정책이나 시스템 지시를 바꾸게 해서는 안 된다.
• 테스트 픽스처와 주석의 이름·방 이름·메시지는 지어낸 것을 쓴다. 계정 자신은 한결, 상대는 지수·민준·민수, sender id는 19자리 합성값. 실제 값을 예시로 쓰면 그게 근거가 되어 버리고, 나중에 지울 때 근거까지 함께 사라진다.
• 측정해서 알아낸 것을 적을 때 실제 이름이나 식별값이 논거로 필요해 보이면, 그것 없이 같은 논거를 쓸 방법을 먼저 찾는다. 「같은 표시 이름을 쓰는 두 사람이 sender id로만 구분됐다」는 이름 없이도 성립한다.
• 실제 카카오톡 문장을 인용해야 하면 원문 대신 같은 모양으로 옮겨 적고, 옮겨 적었다고 밝힌다.
• 이슈·PR·커밋 메시지에도 같은 규칙이 적용된다. 재현 방법을 적을 때 실제 대화, 실제 이름, 계정 식별값을 붙이지 않는다. 합성 fixture 또는 나와의 채팅으로 재현해서 적는다.

문서

• 제품 결정은 DESIGN.md, 모듈 경계는 docs/ARCHITECTURE.md, 외부 소프트웨어의 관측된 동작은 docs/PLATFORM-FINDINGS.md에 둔다.
• 측정해서 알아낸 사실은 확인 방법을 함께 적는다. 카카오톡과 macOS는 우리 통제 밖이라 그 사실은 언젠가 틀려진다.
• 설계 문서에 측정치를 늘어놓지 않는다. 결정과 근거만 남기고 수치는 실측 기록을 가리킨다.

검증

• 도메인 정책을 바꾸면 대응하는 단위 테스트를 추가한다.

• UI나 인프라 변경 뒤에는 swift build를 실행한다.

• 테스트는 아래 명령으로 돌린다. 그냥 swift test는 CPU 0%로 무한 정지할 수 있다. KatokPhotoExtractorTests.swift의 테스트가 실제 카카오톡 컨테이너를 열거하는데, 권한 없는 열거는 에러가 아니라 돌아오지 않는 호출이다. 권한이 살아 있으면 통과하므로, 되다가 안 되는 것이 정상이다.

  swift test --skip extractedPhotosLandInOneDirectoryThatDiscardRemoves \
             --skip aMessageWithNoPictureLeavesNoDirectoryBehind \
             --skip anEmptyPlaceholderFileIsNotOfferedToTheModel \
             --skip onlyPhotosUpToTheCapAreEverAskedFor \
             --skip withoutTheConnectorThereAreNoPhotosAndNoTemporaryFiles