AGENTS.md

Expo HAS CHANGED

Read the exact versioned docs at https://docs.expo.dev/versions/v56.0.0/ before writing any code.

설계 우선 협업 원칙

이 프로젝트의 작업은 단순 기능 구현뿐 아니라 사용자가 현재 구조를 직접 이해하고 중요한 설계 결정을 내릴 수 있도록 진행한다.

설계가 필요한 부분을 임의로 결정해 바로 구현하지 않는다. 사용자가 명시적으로 구현 진행을 승인하기 전까지 설계 단계에서는 코드를 변경하지 않는다.

작업 순서

설계가 포함된 작업은 반드시 다음 순서로 진행한다.

1. 현재 구조(As-Is)를 분석한다.
2. 해결해야 하는 기술적 문제를 정의한다.
3. 실제로 선택할 가치가 있는 설계안 2~3개를 제시한다.
4. 각 설계안의 장단점, 성능, 복잡도, 유지보수성, 확장성을 비교한다.
5. 가장 추천하는 안과 추천 이유를 제시한다.
6. [결정이 필요한 사항]을 정리하고 작업을 멈춘다.
7. 사용자가 설계안을 선택하고 구현을 명시적으로 승인한 뒤에만 코드를 변경한다.
8. 구현 후 실제 코드가 선택한 설계와 일치하는지 다시 검증한다.

의미 없는 대안을 개수만 맞추기 위해 만들지 않는다. 유효한 설계가 하나뿐이라면 그 이유와 제약을 설명한다.

설계 시 필수 분석 항목

각 기능의 설계에서는 최소한 다음 내용을 다룬다.

• 기능의 책임이 속하는 계층
• 책임질 module, entity, feature, widget
• 외부 라이브러리와 프로젝트 domain 사이의 경계
• 데이터 흐름과 방향
• 상태 소유자
• lifecycle 관리자
• 실패가 다른 기능에 미치는 영향
• interface 또는 adapter로 격리할 부분
• 향후 구현 변경 시 교체하기 어려운 부분

가능하면 기능에 적합한 데이터 흐름도를 포함한다.

Input
  ↓
Adapter
  ↓
Domain
  ↓
Use Case
  ↓
UI

설계안 비교 형식

각 설계안은 구조, 장점, 단점을 설명하고 필요에 따라 성능, 복잡도, 유지보수성, 확장성 차이를 함께 비교한다.

설계 결과 마지막에는 반드시 다음 형식으로 사용자가 선택해야 하는 내용을 정리한다.

[결정이 필요한 사항]

1. ...
2. ...
3. ...

이 시점에는 구현하지 않고 사용자의 선택을 기다린다. 중요한 아키텍처 결정을 사용자 승인 없이 확정하지 않는다.

설계 결정 기록

사용자가 선택한 중요한 결정은 구현 후 포트폴리오에서도 설명할 수 있도록 별도의 architecture 문서에 정리할 수 있는 ADR 형태로 기록한다. 코드에는 설계 설명을 위한 과도한 주석을 넣지 않는다.

Decision:
어떤 구조를 선택했는가

Context:
왜 이 결정이 필요했는가

Alternatives:
어떤 대안을 검토했는가

Reason:
왜 이 방식을 선택했는가

Trade-off:
무엇을 얻고 무엇을 포기했는가

Result:
실제 구현 또는 측정 결과는 어땠는가