ikieEngineeringGet started
All posts

개발 원칙아키텍처테스트

원칙은 문서가 아니라 시험에 적어요

원칙을 위키에 적어 두면 바쁠 때 가장 먼저 잊혀요. ikie가 지키는 여덟 가지 원칙을, 어겼던 실제 사례와 어기는 코드를 리뷰 전에 막는 시험과 함께 적었어요.

English
  1. 문app/api/v1 · lib/mcp · 서버 화면

    누구인지 확인하고 받은 값을 검사한 뒤 파사드 하나를 불러요. 스스로 정하지 않아요.

  2. 쓰임새lib/use-cases

    사실 읽기 → 계산 → 쓰기를 이어요. 포트와 계산만 알고, 요청·쿠키·DB를 몰라요.

  3. 계산packages/core · lib/calc

    입력에서 출력만 나와요. DB·시계·네트워크를 부르지 않고, 지금 시각도 인자로 받아요. DB 없이 시험해요.

  4. 데이터lib/data

    DB와 바깥 API를 읽고 쓰기만 해요. 포트 뒤에 숨어서, 바꿔 끼워도 위층은 몰라요.

ikie 서버의 네 층. 문은 쓰임새만 부르고, 쓰임새는 계산과 포트만 알아요. 판단은 가운데 순수 계산 층에 모이고, 이 층이 가장 커요. 층을 건너뛰는 가져오기는 시험이 막아요.

ikie에는 문이 여럿이에요. 웹 앱, iOS 앱, 그리고 사용자가 붙이는 Claude(MCP)가 모두 같은 서버를 불러요. Google, iCloud, Outlook 같은 외부 캘린더와 Notion, Linear 같은 할 일 원본도 붙어요. 문과 바깥이 늘수록 "이 판단은 어디서 하지?"라는 질문이 자주 생기고, 답이 흔들리면 같은 기능이 문마다 조금씩 다르게 움직여요.

그래서 원칙을 정했는데, 원칙을 위키에 적어 두는 것만으로는 부족했어요. 바쁠 때 가장 먼저 잊히거든요. 그래서 원칙에 그것을 지키는 장치를 붙였어요. 대부분은 코드를 읽어 규칙을 확인하는 시험이고, CI가 돌려요. 원칙을 어긴 코드는 사람이 리뷰하기 전에 빨간불을 받아요. 시험으로 막기 어려운 원칙(8번)은 작업 규칙으로 지켜요.

1. 사실만 저장해요

사실만 저장하고, 사실에서 나오는 상태는 저장하지 않아요. 다른 저장한 값에서 다시 만들 수 있으면 저장하지 않아요.

반복 일정의 회차는 규칙에서 언제든 다시 만들 수 있으니 저장하지 않아요(반복 일정은 저장하지 않아요). 유료 플랜(Hyper)도 저장하지 않아요. App Store 구독과 직접 준 권리라는 사실만 적고, 지금 플랜은 요청마다 계산해요. 플랜이 끝나 무료 한도를 넘은 캘린더 계정이 멈추는 것도 저장하지 않고 계산해요. 그래서 다시 구독하면 아무것도 되돌릴 필요가 없어요.

같은 맥락에서, 조건이 바뀌었다고 사용자의 설정이나 데이터를 고쳐 쓰지 않아요. 플랜이 끝나도 지우거나 설정을 바꾸지 않고, 기능마다 정해 둔 대로 막기만 해요.

어긴 사례. 코드 전체를 원칙에 비춰 훑었을 때 저장한 파생 값이 여럿 나왔어요. "이 회차는 없음"이 지운 회차(EXDATE)와 취소한 회차 예외라는 두 모양으로 따로 저장되고 따로 읽히던 것이 그중 하나였어요. 외부 형식을 그대로 맞추려면 두 모양은 남겨야 해서, 저장은 그대로 두고 판단을 함수 하나(occurrenceGone)로 모았어요.

지키는 장치. 모든 DB 칸은 모델 선언(model.ts)에 저장하는 까닭과 외부 캘린더 대응을 적어야 해요. 선언 없는 칸이 생기면 CI가 막아요. 같은 사실을 두 곳에 적는 것은 one-source.test.ts가 막아요. 권한 사다리, 항목 상태 목록, "끝났나" 판단 같은 것들이요.

2. 판단은 서버가 하고, 화면은 그대로 그려요

정책과 규칙 판단은 모두 서버가 해요. 화면은 서버가 정한 것을 보여 주고 입력을 받아요.

캘린더마다 "바꿀 수 있는 것"과 "못 바꾸는 까닭"도 서버가 보내요(can, why). 웹과 iOS는 그대로 그려요. 화면이 직접 정하면 웹과 iOS가 같은 규칙을 두 번 쓰게 되고, 하나만 고쳐지는 날이 반드시 와요.

어긴 사례. 공개 링크로 본 캘린더를 구독할 수 있는지, 반복 일정의 "이 회차만" 저장이 반복 규칙까지 바꾸는지, 반복하는 할 일에 마감을 둘 수 있는지를 화면이 다시 정하고 있었어요. 조용히 버려지던 입력도 있었어요. 판단을 모두 서버로 옮기고, 조용히 버려지던 것은 분명한 오류(series_only, due_repeat)로 바꿨어요.

지키는 장치. 화면 컴포넌트는 서버 쪽 코드를 가져오지 못하고, 서버는 생성된 API 클라이언트로만 불러요. Next.js의 서버 동작("use server")은 아예 두지 않아요. 화면도 iOS와 MCP처럼 공개 API를 부르게 하려고요.

3. 순수 계산이 가장 큰 층이에요

판단은 입력에서 출력만 나오는 순수 함수로 해요. DB, 시계, 네트워크를 부르지 않고, 지금 시각도 인자로 받아요.

권한(canEdit), 반복 펼치기, 저장 계획, 울릴 알림, 남는 시간, 외부 캘린더와의 3방향 합치기(three-way merge)가 모두 순수 계산이에요. 데이터 층은 판단에 쓸 사실을 읽고, 계산이 정한 쓰기를 적용하기만 해요. 예를 들어 반복 시리즈를 나눌 수 있는지는 데이터 층이 잠근 뒤 읽은 사실을 받아 순수 함수 하나가 정해요.

// 데이터 층: 잠그고 사실을 읽어 계산에 묻기만 해요
const block = splitBlock({ rows, external, pendingAlarmClaims }, from, expectedRevision, now);
if (block) throw new PlanError(block);

이렇게 하면 가장 까다로운 규칙을 DB 없이 몇 밀리초 안에 시험할 수 있어요. 시계를 인자로 받으니 "5분 넘게 멈춘 알림" 같은 시간 조건도 시험에서 그대로 재현돼요.

지키는 장치. 계산 층은 허락한 순수 라이브러리만 가져올 수 있고, Date.now(), 난수, fetch, 환경 변수를 쓰면 시험이 막아요. 데이터 층이 판이나 알림을 계산하려 해도 막아요.

4. 문은 얇게, 파사드는 하나

공개 API, MCP, 서버 화면은 모두 같은 파사드 하나를 불러요. 문은 누구인지 확인하고 요청 본문을 검사할 뿐, 스스로 정하거나 부수 효과를 두지 않아요.

어긴 사례. 이 원칙은 버그에서 나왔어요. 사용자가 붙인 Claude(MCP)로 Google 캘린더의 일정을 고치면 Google에 올라가지 않았어요. 고친 일정을 외부로 보내는 일을 공개 API의 문(HTTP 어댑터)이 하고 있었고, MCP는 또 하나의 문이라 그 일을 몰랐던 거예요. 문에 같은 코드를 하나 더 붙이면 증상은 사라지지만, 다음에 붙는 문에서 또 생겨요.

그래서 문을 고치지 않고 구조를 바꿨어요. 모든 문이 파사드 하나를 부르게 하고, 항목 쓰기는 한 길(writeItems)로 모았어요. 적용하고, 바뀐 외부 일정은 응답한 뒤 그 캘린더 주인의 계정으로 보내요. 무엇을 보낼지는 순수 계산이 정해요. 이제 어느 문으로 고쳐도 같은 일이 일어나요.

지키는 장치. 문이 쓰임새 모듈을 직접 가져오거나, 보는 시간대·언어 규칙을 다시 쓰거나, 외부 보내기를 정하면 시험이 막아요. 쓰임새의 모든 일에는 공개 API 길이 있어야 해요. 웹, iOS, MCP가 같은 길을 부르게 하려고요.

5. 경계는 모두 포트로 이어요

바깥(외부 캘린더, DB, 비밀 보관, 시계)도, 안의 층 사이도 선언한 인터페이스로만 이어요. 새 바깥을 붙일 때는 어댑터만 더해요.

캘린더 동기화 엔진은 하나이고, CalendarPort라는 모양만 알아요. Google, iCloud(CalDAV), Outlook, .ics 주소 구독은 모두 그 포트 뒤의 어댑터예요. 칸마다 3방향으로 합치는 판단은 순수 계산에 있어서, 어떤 외부든 같은 규칙으로 맞춰요. 할 일 원본도 같은 모양이에요. Notion, Todoist, Linear, Google Tasks, Microsoft To Do, GitHub이 하나의 엔진과 각자의 어댑터로 붙어요.

이 덕분에 MCP를 붙일 때도 서버를 새로 짜지 않았어요. MCP 서버는 공개 API와 같은 파사드, 같은 스키마를 부르는 얇은 어댑터예요.

지키는 장치. 동기화 엔진이 어느 외부의 어댑터나 클라이언트를 가져오거나 어댑터가 DB를 알면 시험이 막아요. API 라우트와 서버 화면도 데이터 층을 직접 부르지 못하고, 포트와 조립 지점(포트에 구현을 붙이는 한 곳)만 써요.

6. 두 앱의 규칙은 데이터로 한 번 적어요

웹과 iOS가 함께 지켜야 하는 앱 정책은 플랫폼마다 쓰지 않고, 데이터로 한 번 선언해요. 두 앱의 해석기를 같은 시나리오로 시험해요.

"무엇을 언제 받고, 바뀐 것을 어떻게 보이나"는 업무 판단은 아니지만 두 앱이 똑같아야 해요. 받는 단위, 미리 받기, 넘기는 동안 고른 날을 언제 적을지 같은 것들이요. 이것을 packages/policy에 데이터로 적고, 웹은 TypeScript 해석기로, iOS는 그 데이터에서 만든 Swift 코드와 Swift 해석기로 읽어요. 두 해석기는 같은 시나리오 JSON으로 시험해요.

어긴 사례. 해석기를 시험만 부르고 앱 코드는 제 나름대로 하는 빈틈이 있을 수 있어요. 코드 그래프로 이것을 검사하자 실제로 세 곳이 나왔어요. 예를 들어 iOS가 판의 어느 날을 다시 쓸지 정책 해석기가 아닌 자기 코드로 고르고 있었어요.

지키는 장치. 정책 규칙마다 선언한 플랫폼의 구현이 있어야 하고, 그 구현을 앱 코드가 써야 해요. 코드에서 자동으로 만드는 그래프(TypeScript는 컴파일러 API, Swift는 tree-sitter)가 이것을 확인하고, CI가 막아요.

7. 서버에 LLM을 넣지 않아요

앱 서버는 판(캘린더, 할 일)과 규칙이에요. 판단은 사용자가 붙인 Claude가 MCP로 해요. AI만을 위한 표, 칸, 규칙을 만들지 않아요.

사용자의 Claude는 사용자가 붙인 도구예요. 따로 계정이 있는 행위자가 아니라 사용자와 같은 권한으로 일하고, 이력에는 "연결한 앱"으로 남아요. Claude가 필요한 것은 앱 기능(할 일, 안에 넣기, 태그, 메모)으로 해요. 한때 AI 작업 전용 표와 칸이 있었는데, 기록을 메모·링크·태그로 옮긴 뒤 모두 지웠어요.

예외는 기기 안 모델 하나예요. "내일 3시 치과" 같은 한 줄을 읽을 때 iPhone과 Mac에서는 기기 안 모델을 쓸 수 있어요. 이것도 규칙으로 읽는 파서와 같은 포트로 읽고, 모델이 없거나 실패하면 규칙 읽기가 그대로 받쳐 줘요. 두 읽기는 같은 시험 세트로 정확도를 재요. 그리고 읽기와 만들기를 나눴어요. 글을 읽는 함수는 해석 전용 API만 부르고, 만들기 API는 값만 받아요.

지키는 장치. 만들기 경로가 글을 읽는 함수를 부르면 시험이 막아요. 읽고 바로 만드는 길은 없어요.

8. 만들기 전에 찾고, 땜빵 말고 구조로 고쳐요

잘 관리되는 오픈소스가 있으면 먼저 써요. 직접 만들면 까닭을 남겨요. 고칠 때는 증상이 아니라 그 증상을 낳은 구조를 고쳐요.

반복 규칙은 rrule, iCalendar 파일은 ical.js, CalDAV는 tsdav, 고르기 동작은 Base UI, 색은 Radix Colors, 디자인 토큰은 Style Dictionary, iOS API 클라이언트는 swift-openapi-generator, 시험 DB는 PGlite가 맡아요. 직접 만든 것은 PR에 까닭을 적어요. 주 보기 넘기기에서 UICollectionView 대신 작은 페이저를 직접 둔 것이 그 예예요.

어긴 사례. 주 보기가 끊길 때, 홈 화면 파일들에는 "예전엔 끊겼다" 같은 주석이 44개 있었어요. 한 곳을 막으면 다른 곳에서 다시 나왔다는 뜻이에요. 이번엔 구조를 바꿨고, 단계마다 숫자를 쟀어요. 코드 전체를 원칙에 비춰 훑은 검토도 같은 방식이었어요. 어긋난 곳 168곳을 찾았고, 166곳을 고쳤어요. 하나는 잘못 본 것이었고, 하나는 디버그용 데모라 까닭을 적고 남겼어요.

대체 동작(fallback)도 같은 원칙을 따라요. 의도를 적을 수 있을 때만 두고, 아니면 분명하게 실패해요. 외부 캘린더에 이어진 반복 시리즈를 나누지 못하면 반쯤 맞게 나누지 않고 409로 거절해요.

원칙 밖의 작은 규칙들

원칙만큼 크지 않지만, 같은 방식으로 시험이 지키는 규칙도 있어요.

규칙까닭지키는 것
손으로 쓴 파일은 300줄까지, 웹은 한 줄도 300자까지한 번에 다 읽히는 크기웹·Swift 크기 시험 (지금 300줄 넘는 파일 0개)
화면 CSS에 색·글자 크기를 숫자로 쓰지 않아요디자인 토큰 하나로 웹·iOS를 함께스타일 시험, 토큰 대비 시험
화면 문구는 6개 언어 파일에 함께글로벌 앱키·넣는 값·ICU 문법 시험
API 길을 더하면 OpenAPI 문서에도iOS와 MCP가 같은 계약을 읽게OpenAPI 시험
린트 경고도 막아요경고가 쌓이면 아무도 안 봐요Biome

시험이 원칙을 지키면 생기는 일

원칙을 시험으로 지키면 리뷰에서 원칙을 다시 설명할 일이 줄어요. 시험 이름이 곧 원칙이고, 빨간불에는 어느 원칙을 어겼는지가 적혀 있어요. 원칙을 바꾸고 싶으면 시험을 고치는 PR로 이야기하면 돼요.

가장 크게 도운 건 새 문과 새 바깥을 붙일 때였어요. iOS 앱은 웹과 같은 공개 API를 부르고, MCP는 같은 파사드를 부르는 어댑터이고, 새 캘린더나 할 일 원본은 어댑터 하나예요. 매번 "이번엔 어디를 고쳐야 하지?"를 묻지 않아도 돼요. 답이 구조에 이미 있으니까요.

The ikie teamikie is a calendar for your events and to-dos in one place. Here we write about the problems we run into while building it, and how we solve them.