설계 문서: 어떻게 만들었고 왜 그렇게 정했는가
이 페이지는 설계 문서에 무엇을 적고, 언제 쓰고, 어떻게 유지하는가에 답한다. 스펙이 “무엇을 왜”를 맡았다면 설계는 “어떻게, 왜 그 방식으로”를 맡는다.
이 장에서 처음 나오는 말2개
규약Convention- 이 레포에서 같은 종류의 문제를 항상 같은 방식으로 푸는 약속. 수식 주입 방지 방법, 의존 방향 같은 것.
결정 기록Decision Record- 왜 그 방식을 골랐고 무엇을 버렸는지 남긴 짧은 기록. 다음 세션이 같은 고민을 반복하지 않게 한다.
설계가 없으면 같은 결정을 매번 다시 한다
섹션 제목: “설계가 없으면 같은 결정을 매번 다시 한다”CSV 내보내기를 만들며 “제목이 =로 시작하면 앞에 작은따옴표를 붙인다”고 정했다. 이 결정이
완료된 계획 파일 안에만 있으면, 다음 달 “댓글 CSV 내보내기”를 만드는 세션은 그 계획을 찾아
읽거나 다른 방식을 고른다. 두 기능의 CSV가 서로 다르게 동작하기 시작한다.
계획을 가로지르는 규약은 계획 밖으로 꺼내 한 곳에 둔다. 그 파일을 AGENTS.md가 “CSV 출력을 만들거나 바꿀 때 읽는다”로 연결하면 다음 세션은 결정을 물려받는다.
설계 문서에 적는 것
섹션 제목: “설계 문서에 적는 것”영역 하나에 파일 하나다. 한 파일은 현재 구조나 규약을 설명하고, 그렇게 정한 이유를 짧게 붙인다.
| 종류 | 답하는 질문 | 파일 예 |
|---|---|---|
| 구조 | 서비스·모듈이 어떻게 나뉘고 의존 방향은 무엇인가 | architecture.md |
| 데이터 | 스키마·마이그레이션·생성 파일을 어떻게 다루는가 | database.md |
| 규약 | 같은 종류의 문제를 어떻게 푸는가 | csv-output.md, error-handling.md |
| 결정 | 왜 그 방식이고 무엇을 버렸는가 | 각 문서 안의 “결정” 절 |
스펙처럼 ID를 붙일 필요는 없다. 파일명과 제목으로 찾을 수 있으면 된다.
예시: CSV 출력 규약
섹션 제목: “예시: CSV 출력 규약”CSV 내보내기 계획이 끝날 때 만든 파일이다. 계획 안에 있던 결정 중 다음 기능에도 적용될 것만 옮겼다.
# CSV 출력 규약
CSV를 내려주는 모든 API에 적용한다. 첫 적용은 업무 목록 내보내기(exec-plans/completed/0007-csv-export.md).
## 규약
- 생성은 packages/csv의 `toCsv()`만 쓴다. 직접 문자열을 이어 붙이지 않는다.- 인코딩은 UTF-8 with BOM. Excel이 한글을 깨뜨리지 않게 하기 위해서다.- 셀 값이 `=`·`+`·`-`·`@`로 시작하면 앞에 `'`를 붙인다. 스프레드시트 수식 실행을 막는다.- 건수 제한을 넘으면 파일 대신 413과 제한 안내를 반환한다. 일부만 내려주지 않는다.- 조회는 화면 목록과 같은 권한·필터 함수를 쓰되 페이지 제한만 뺀 별도 함수를 둔다.
## 결정
- 화면 목록 함수를 그대로 재사용하지 않은 이유: 페이지 제한이 함수 안에 있어 전체 조회가 불가능했다. 권한·필터 부분을 분리해 두 함수가 공유한다.- 비동기 처리를 하지 않은 이유: 첫 요구가 1,000건 이하였다. 초과 요구가 생기면 이 문서를 고친다.“결정” 절이 있어야 다음 세션이 “왜 목록 함수를 안 썼지”를 다시 조사하지 않는다. 버린 선택지를 한 줄 적는 것이 그 효과의 대부분이다.
언제 쓰는가
섹션 제목: “언제 쓰는가”| 시점 | 할 일 |
|---|---|
| 계획이 완료될 때 | 계획의 결정 중 다음 작업에도 적용될 것을 설계 문서로 옮긴다. 이번 작업에만 해당하는 것은 계획에 남긴다 |
| 두 번째 기능이 같은 규약을 필요로 할 때 | 첫 계획에서 규약을 꺼내 파일을 만들고 두 계획이 링크한다 |
| 구조나 의존 방향을 바꿀 때 | 바꾸기 전에 해당 문서를 읽고, 바꾼 뒤 문서를 고친다 |
| 레포를 처음 정리할 때 | 이미 코드에 있는 규약을 한두 파일로 적는다. 없는 규약을 미리 만들지 않는다 |
규약이 타입·lint·테스트로 이미 강제되고 있으면 문서로 다시 적지 않는다. 문서는 도구가 잡지 못하는 것, 즉 “왜”와 “어느 경우에”를 맡는다.
어떻게 유지하는가
섹션 제목: “어떻게 유지하는가”설계 문서는 현재 상태를 말한다. 코드와 다른 설계 문서는 없는 것보다 해롭다.
- 그 영역을 고치는 작업은 AGENTS.md의 읽기 조건으로 문서를 먼저 읽게 한다. 작업이 끝나면 달라진 부분을 고친다.
- 결정이 뒤집히면 옛 결정을 지우지 말고 “대체됨”으로 표시하고 새 결정과 이유를 적는다. 왜 바꿨는지가 다음 결정의 근거가 된다.
- 계획 파일을 링크할 때는
completed/경로로 적는다. 계획은 완료되면 폴더가 바뀐다. - 문서가 코드와 어긋난 것을 발견하면 그 자리에서 고친다. 별도 정리 작업을 기다리지 않는다.
이해 확인
섹션 제목: “이해 확인”댓글 CSV 내보내기를 만드는 세션이 수식 주입 방지 방법을 묻는다. 어디를 보게 할까?
design-docs/csv-output.md다. AGENTS.md에 “CSV 출력을 만들거나 바꿀 때 읽는다”가 있으면
묻기 전에 읽었을 것이다. 없다면 그 조건을 추가한다.
계획에 적힌 “M1에서 조회 함수를 분리함”을 설계 문서로 옮겨야 할까? 분리한 결과와 이유는 옮긴다. 다음 CSV 기능도 그 함수를 쓰기 때문이다. “M1에서”라는 진행 정보는 계획에 남긴다.