AA가 프로젝트 착수 후 30일 동안 해야 할 일과 필수 산출물

애플리케이션 아키텍트(AA)의 첫 30일은 개발 기간 전체의 비용을 정한다. 이때 정한 구조, 표준, 기술 선택은 개발자 수십 명이 몇 달 동안 따라야 하는 기준이 되고, 늦게 바꿀수록 고치는 값이 커진다. 이 글은 착수 후 30일을 주 단위로 나눠 해야 할 일과 그 주에 반드시 남겨야 할 산출물을 정리한 것이다.

30일을 한눈에

순서가 중요하다. 1~2주차를 건너뛰고 3주차부터 시작하면 "멋있지만 이 프로젝트에 안 맞는" 아키텍처가 나온다.

1주차: 현황과 제약 파악

첫 주에는 설계하지 않는다. 읽고 묻는다.

할 일

• 제안요청서(RFP), 제안서, 계약서의 과업 범위를 끝까지 읽는다. 특히 비기능 요구사항(성능, 보안, 가용성)과 "~를 준수한다"로 끝나는 문장에 표시한다. 이 문장들이 나중에 검수 기준이 된다.
• 이해관계자를 만난다. 발주 부서, 운영 부서, 보안 담당, 인프라 담당, 연계 대상 시스템 담당자를 빠뜨리지 않는다. 운영 부서와 보안 담당은 늦게 만날수록 설계를 뒤집는 요구를 가져온다.
• 현행 시스템을 조사한다. 서버 구성, 사용 중인 프레임워크와 버전, DB, 연계 시스템과 방식(API, 파일, DB 링크), 월별 사용량과 피크 시간대를 확인한다.
• 바꿀 수 없는 제약을 적는다. 정해진 인프라(온프레미스, 특정 클라우드), 필수 표준 프레임워크, 망 분리 여부, 개인정보 처리 기준, 지정된 DBMS 같은 것들이다.

산출물

• 이해관계자 목록: 이름, 역할, 관심사, 의사결정 권한
• 현행 시스템 분석서: 구성도, 기술 스택, 연계 목록, 사용량
• 제약사항·가정 목록: 확인된 제약과 아직 확인 못 한 가정을 나눠 적는다. 가정에는 확인할 사람과 기한을 붙인다.
• 초기 위험 목록: "연계 대상 시스템의 API 문서가 없음"처럼 구체적으로 적는다.

2주차: 아키텍처를 움직이는 요구사항 찾기

요구사항 수백 개 중 아키텍처를 바꾸는 것은 많지 않다. 그것을 골라내는 주다.

할 일

• 품질 요구사항을 숫자로 바꾼다. "빠른 응답"은 요구사항이 아니다. "피크 시간 동시 사용자 2,000명에서 조회 화면 95%가 2초 안에 응답"처럼 조건, 측정 대상, 기준값을 함께 적는다. 숫자를 발주처와 합의하지 못하면 검수 때 다툼이 생긴다.
• 품질 속성 시나리오를 만든다. 자극(무슨 일이 생기나), 환경(언제), 응답(시스템이 어떻게 반응하나), 측정(무엇으로 판단하나) 네 칸으로 정리하면 모호함이 줄어든다.
• 아키텍처 핵심 요구사항(ASR)을 고른다. 기준은 "이 요구사항이 바뀌면 구조가 바뀌는가"다. 대용량 배치, 외부 기관 실시간 연계, 24시간 무중단, 개인정보 암호화 같은 것들이 보통 여기에 든다.
• 요구사항끼리 충돌하는 지점을 찾는다. 보안 강화와 응답 속도, 유연한 확장과 일정이 자주 부딪친다. 충돌은 AA 혼자 정하지 말고 우선순위를 발주처와 합의해 기록한다.

산출물

• 품질 요구사항 정의서: 항목마다 측정 방법과 기준값
• ASR 목록: 요구사항 ID, 선정 이유, 영향받는 구조

3주차: 구조와 표준 결정

이제 설계한다. 이 주의 결과물은 개발자가 바로 따라 할 수 있어야 한다.

할 일

• 후보 아키텍처를 두세 개 놓고 ASR 기준으로 비교한다. 비교표를 남겨야 나중에 "왜 이렇게 했냐"는 질문에 답할 수 있다.
• 애플리케이션 구조를 정한다. 레이어 구성, 업무 모듈 경계, 모듈 사이 호출 규칙(직접 호출 허용 여부, 공통 모듈 위치)을 그림과 함께 적는다.
• 기술 스택과 버전을 확정한다. 프레임워크, 라이브러리, 빌드 도구, 런타임 버전까지 적는다. 버전을 비워 두면 개발자마다 다른 버전을 쓴다.
• 주요 결정을 ADR로 남긴다. 한 결정에 한 장, "배경 / 결정 / 고려한 대안 / 결과(감수하는 단점)" 네 칸이면 충분하다.
• 개발 표준을 만든다. 패키지 구조, 이름 규칙, 예외 처리, 로그 형식과 레벨, 트랜잭션 경계, 공통 응답 형식, 보안 코딩 규칙(입력 검증, SQL 작성 방식)을 정한다.
• 인터페이스 목록을 만든다. 내부·외부 연계마다 방식, 주기, 데이터 형식, 담당자를 적는다. 상세 명세는 이후에 채워도 되지만 목록은 이 주에 있어야 한다.

산출물

• 아키텍처 정의서 초안: 논리·물리 구성도, 레이어 구조, 기술 스택, 품질 요구사항 대응 방안
• ADR 묶음
• 개발 표준 정의서
• 인터페이스 목록

ADR 예시는 이 정도면 된다.

# ADR-003 외부 기관 연계는 비동기 큐로 처리한다

- 배경: 외부 기관 API 응답이 최대 10초까지 늦어지고 장애가 잦다.
- 결정: 신청 접수는 즉시 응답하고, 연계 호출은 메시지 큐 소비자가 처리한다.
- 대안: 동기 호출 + 타임아웃(장애가 화면까지 전파되어 기각).
- 결과: 처리 상태 조회 화면과 재처리 기능이 추가로 필요하다.

4주차: 결정을 코드로 검증

문서로만 끝난 아키텍처는 개발 2주 차에 무너진다. 마지막 주에는 위험한 결정부터 실제로 돌려 본다.

할 일

• 위험이 큰 기술은 PoC로 확인한다. 처음 쓰는 프레임워크, 성능 목표가 빡빡한 구간, 외부 연계, 인증 연동이 대상이다. PoC는 "되는지"뿐 아니라 2주차에 정한 숫자를 넘는지까지 측정한다.
• 샘플 애플리케이션을 만든다. 화면 하나, API 하나, 배치 하나 정도로 표준(레이어, 예외, 로그, 트랜잭션)을 전부 지킨 레퍼런스 코드다. 개발자는 문서보다 이 코드를 복사해 시작하므로, 샘플이 곧 표준이다.
• 개발 환경을 준비한다. 저장소와 브랜치 전략, 빌드·배포 파이프라인, 정적 분석 도구, 로컬 환경 구성 방법을 한 문서에 모은다.
• 아키텍처 검토를 연다. 발주처, PM, 각 파트 리더, 운영·보안 담당이 함께 보고 ASR이 어떻게 반영됐는지 확인한다. 지적 사항은 조치 계획과 함께 기록한다.

산출물

• PoC 결과 보고서: 목표, 방법, 측정값, 결론, 남은 위험
• 샘플 애플리케이션과 사용 가이드
• 개발 환경 구성 가이드
• 아키텍처 검토 결과와 조치 계획

필수 산출물을 왜 남기는가

자주 하는 실수

• 기술 선택부터 한다. 요구사항을 보기 전에 익숙한 스택을 정해 두면, 그 뒤의 분석은 결정을 합리화하는 일이 된다.
• 품질 요구사항을 형용사로 둔다. "안정적인", "빠른"은 측정할 수 없다. 숫자가 없으면 아키텍처도 검증할 수 없다.
• 문서만 쓰고 코드를 안 쓴다. 샘플 애플리케이션이 없으면 표준은 지켜지지 않는다.
• 운영·보안 담당을 늦게 만난다. 망 구성, 접근 통제, 로그 보관 기준은 구조를 바꾸는 요구사항이다.
• 결정 이유를 남기지 않는다. 석 달 뒤 "왜 이렇게 했지?"에 아무도 답하지 못하면 같은 논쟁을 다시 한다.

30일 점검표

• 과업 범위의 비기능 요구사항과 준수 항목을 모두 표시했다
• 운영·보안·인프라·연계 담당자를 모두 만났다
• 가정마다 확인할 사람과 기한이 있다
• 품질 요구사항에 측정 방법과 기준값이 있고 발주처와 합의했다
• ASR 목록과 선정 이유가 있다
• 기술 스택에 버전까지 적혀 있다
• 주요 결정마다 ADR이 있다
• 개발 표준과 그것을 지킨 샘플 코드가 있다
• 위험한 기술은 PoC로 측정까지 마쳤다
• 아키텍처 검토를 열고 지적 사항의 조치 계획을 남겼다

첫 30일의 목표는 완벽한 설계가 아니다. 개발자가 내일 아침 무엇을 어떻게 만들지 헷갈리지 않는 상태, 그리고 그 기준이 왜 그런지 설명할 수 있는 기록을 남기는 것이다.