유행 기술보다, 지금 감당할 수 있는 가장 단순한 구조 고르기

시작 전

아키텍처는 그림 자랑이 아니라 책임의 지도입니다

구조가 복잡해지면 기능이 자동으로 좋아지지 않습니다. 연결이 늘수록 권한·실패 지점·복구 절차도 늘어납니다.

• 단일 구조: 한 Agent가 파일과 문서를 읽고 결과를 남기는 기본 흐름
• 연결 구조: 외부 API·MCP와 주고받는 흐름
• 분업 구조: 여러 Agent나 작업자가 역할을 나누는 흐름
• ADR: 바꾸기 어렵고 대안이 있던 결정을 기록하는 문서

01 · 흐름 지도

핵심 행동을 다섯 관절로 잘라 보기

사용자의 한 행동이 지나가는 관절만 그립니다. 관절마다 파일로 충분한지 확인합니다.

1. 01

   W05 행동 문장 다시 읽기

   왜 하나요? 구조가 기능 욕심에서 출발하지 않게 합니다.

   할 일 입력부터 검토 가능한 결과까지 한 문장을 골라 범위를 고정합니다.

   복사해서 써도 되는 요청

   W05 명세에서 첫 구현에 필요한 행동 문장 하나와 출처 판정을 찾아줘.

   정상이라면 구조 그림의 시작과 끝이 사용자 행동으로 정의됩니다.

2. 02

   입력·처리·검증·저장·승인으로 나누기

   왜 하나요? 외부 도구가 필요한 곳을 보이게 합니다.

   할 일 다섯 관절마다 담당 주체와 필요한 상태를 한 줄씩 씁니다.

   정상이라면 파일로 끝나는 관절과 연결이 필요한 관절이 분리됩니다.

3. 03

   각 관절에 “파일로 되나?” 묻기

   왜 하나요? 확장을 조건 뒤로 미룹니다.

   할 일 아니오인 경우 빈도·크기·권한·동시성 조건을 근거로 적습니다.

   복사해서 써도 되는 요청

   각 관절의 파일 처리 가능 여부와 아니오의 조건을 제안해줘. 근거 없는 확장은 표시해줘.

   정상이라면 “나중에 쓸 것 같아서”가 사라집니다.

02 · 비교

같은 명세를 세 구조로 그려 비용을 비교하기

정답 기술을 맞히는 시간이 아니라 같은 행동을 세 구조로 보며 차이를 이해하는 시간입니다.

1. 01

   세 그림을 같은 크기로 그리기

   왜 하나요? 비교 대상은 같게 유지합니다.

   할 일 입력·처리·결과가 같은 위치에 오도록 단일·연결·분업 구조를 나란히 놓습니다.

   정상이라면 기술 이름이 아니라 경로 차이가 보입니다.

2. 02

   권한·실패 지점·복구 비용으로 평가하기

   왜 하나요? 편리함만 보고 연결을 추가하지 않습니다.

   할 일 열어야 하는 권한, 멈출 지점 수, 재개 절차 길이를 비교합니다.

   복사해서 써도 되는 요청

   세 구조를 권한·실패 지점·복구 단계·운영 부담으로 표로 비교해줘.

   정상이라면 어떤 비용을 감당하는 선택인지 말할 수 있습니다.

3. 03

   최소 구조를 기본안으로 선언하기

   왜 하나요? 확장은 조건이 확인된 뒤에도 늦지 않습니다.

   할 일 현재 MVP를 끝까지 통과시키는 가장 단순한 안과 확장 조건을 적습니다.

   정상이라면 지금 하지 않을 일이 함께 남습니다.

03 · 결정 기록

나중에 후회할 결정을 네 줄로 남기기

모든 선택이 아니라 되돌림 비용이 크고 대안이 있었던 결정만 기록합니다.

1. 01

   결정·대안·근거·재검토 조건 쓰기

   왜 하나요? 기술 이름보다 판단 조건을 보존합니다.

   할 일 왜 골랐고 무엇을 비교했으며 언제 다시 볼지를 네 줄로 적습니다.

   정상이라면 구조를 바꿔도 이유를 다시 추측하지 않습니다.

2. 02

   동료가 그림만 보고 질문하게 하기

   왜 하나요? 기록이 실제로 이해되는지 확인합니다.

   할 일 “어떤 조건이면 바꾸나요?”를 물어보고 빈칸을 보완합니다.

   정상이라면 ADR이 팀의 재검토 안내문이 됩니다.