폴더 이름은 파일이 어떤 비즈니스 영역에 속하는지 알려줍니다. 파일 이름은 그 비즈니스 영역 안에서 어떤 역할을 하는지 알려줍니다. 예를 들어 product.document.ts는 저장되는 상품 데이터를 설명하고, Product.View.tsx는 상품 데이터를 화면에 어떻게 보여줄지 설명합니다.

모듈을 작은 비즈니스 부서라고 생각하면 쉽습니다. product 모듈은 상품에 어떤 필드가 있는지, 어떻게 저장하는지, 사용자가 어떻게 요청하는지, 관리자 화면에서 어떻게 보여줄지까지 다룰 수 있습니다. 각 파일은 그중 하나의 역할을 맡습니다.

이 파일들은 비즈니스 모델의 데이터, 서버 로직, API 표면, 상태를 설명합니다. 상품, 주문, 사용자, 청구서, 예약 같은 기능을 만들 때 가장 자주 다루게 됩니다.

abstract 파일은 LLM만을 위한 파일이 아닙니다. 도메인 지식을 코드 옆에 두어 사람과 agent가 구현 파일을 수정하기 전에 비즈니스 불변 조건을 이해할 수 있게 합니다.

UI 접미사 다섯 개도 컴포넌트의 크기 다섯 단계가 아닙니다. 각각 다른 질문에 답합니다. 사용자가 한 레코드를 어떻게 편집하는지, 목록에서 한 레코드가 어떻게 보이는지, 단독 페이지에서 어떻게 보이는지, 페이지 구역이 어떻게 조립되는지, 그리고 모델이 제공하는 부가 동작이 무엇인지입니다. 각 행의 맨 앞은 그 파일이 클라이언트 경계의 어느 쪽에 있는지입니다:

Akan 파일 이름은 두 가지 패턴을 사용합니다. 비즈니스 핵심 파일은 모델 이름을 lower camel case로 쓰고, UI 파일은 PascalCase로 씁니다.

이 규칙을 지키면 모듈을 눈으로 훑기 쉬워집니다. lib/product/를 열었을 때 product.* 파일은 비즈니스 로직이고 Product.* 파일은 UI라는 것을 바로 알 수 있습니다. 새 조회, 화면 컴포넌트, 서버 동작을 어디에 추가할지 빠르게 판단할 수 있습니다.

ui/와 webkit/ 아래 파일은 보통 @apps/myapp/ui, @libs/shared/webkit 같은 barrel 파일을 통해 export됩니다. import를 예측하기 쉽고 최적화하기 좋게 유지하려면, 한 파일에는 대표 export 하나를 두고 파일명과 export 이름을 맞추는 것을 권장합니다.

이 규칙은 비즈니스가 커질수록 특히 유용합니다. 스토어, 관리자 앱, 파트너 앱이 모두 ProductCard를 가져다 쓰더라도 실제 구현 위치를 자세히 알 필요가 없습니다.

페이지는 깊은 파일 경로 대신 패키지 진입점에서 비즈니스 이름으로 import합니다.

모든 폴더 타입이 모든 파일 타입을 쓰는 것은 아닙니다. database module은 전체 파일 구성을 가질 수 있고, service module은 동작 중심이며, scalar module은 재사용 값 정의 중심입니다.

폴더의 비즈니스 역할에 따라 파일 구성을 선택합니다. product는 저장하는 대상이므로 document와 store 파일을 가질 수 있습니다. _payment는 수행하는 기능이므로 보통 service와 signal 중심입니다. money는 재사용 값 형태이므로 작고 정의 중심으로 유지합니다.

이름이 달라지는 것은 abstract 파일 하나입니다. service 모듈은 폴더의 밑줄을 빼므로 lib/_payment/에는 payment.abstract.md를 둡니다.

어떤 파일을 만들어야 할지 모르겠다면, 해결하려는 비즈니스 질문에서 시작하면 됩니다.

예를 들어 '고객이 주문을 볼 수 있나요?'는 View로 이어집니다. '고객이 주문을 취소할 수 있나요?'는 signal과 service로 이어집니다. '주문이 어떤 필드를 저장하나요?'는 document로 이어집니다.