FE권병준 FRONTEND DEVELOPER
이력서 Notes
NOTES / 01 / 2026.10.21

이슈가 이어져도 섞이지 않는 스펙 문서.

한 줄 결론

AI가 다음 작업에서 다시 읽을 스펙 문서는 고치는 시점에 따라 파일을 나눈다. 지금 동작, 판단 이유, 이슈별 작업 기록을 각각 따로 둔다.

쉽게 보기

AI-DLC(AI-Driven Development Life Cycle)는 코드를 짜기 전에 요구사항, 수용조건, 설계, 작업 목록을 문서로 먼저 쓰고, AI가 그 문서를 읽으며 구현하는 방식이다. AWS가 처음 공개한 버전은 저장소 루트의 폴더 하나에 작업 하나의 문서만 두었고, 새 작업을 시작하면 그 폴더를 덮어썼다. 이 글은 그 문서를 기능마다 폴더로 나눠 남기는 방식을 전제로 한다.

log-load/
  requirements.md   배경과 범위
  stories.md        사용자 스토리와 수용조건. AC-1, AC-2처럼 번호를 붙인다
  design.md         설계
  plan.md           작업 목록. 커밋 하나에 대응하는 작업에 B1, B2처럼 번호를 매긴다
  decisions.md      판단과 이유. D-1, D-2처럼 번호를 매긴다

이슈를 시작할 때 사람과 AI가 함께 이 문서를 쓰고, 구현 단계에서는 AI가 plan.md의 작업을 하나씩 진행하며 커밋한다. 이슈 하나를 스펙부터 구현까지 끝내기에는 잘 맞는다.

문제는 같은 기능에 새 이슈가 들어올 때 생긴다. 로그 수집 기능을 만든 뒤 전송 순서를 고치는 이슈가 이어졌다고 하자. 두 번째 이슈의 작업을 같은 log-load/ 문서에 이어 쓰면 아래 세 가지가 문제가 된다.

문제가 되는 것무슨 일이 생기나
지금 동작첫 이슈의 수용조건에 두 번째 이슈에서 바뀐 동작이 섞인다. 어느 쪽이 지금 동작인지 문서만 봐서는 모른다.
작업 번호첫 이슈가 B1~B5를 썼으니 두 번째 이슈의 첫 작업은 B6이 된다. 그런데 커밋 메시지에는 이슈 기준으로 B1이라고 적는다.
폴더 이름폴더 이름이 첫 이슈 범위(예: log-load)라 다음 이슈와 맞지 않는다. 같은 기능의 문서 폴더가 둘 생기기도 한다.

사람은 문서가 조금 섞여도 맥락으로 읽어 낸다. 하지만 AI는 다음 작업에서 이 문서를 지금 동작의 근거로 그대로 읽는다. 문서가 섞여 있으면 AI는 틀린 전제로 구현한다.

그래서 문서를 고치는 시점에 따라 셋으로 나눈다.

log/
  README.md        지금 동작. 동작이 바뀔 때마다 고친다
  decisions.md     판단과 이유. 판단이 생길 때 추가하고 지우지 않는다
  tickets/
    ISSUE-1-load.md              이슈별 작업 기록. 이슈가 끝나면 고치지 않는다
    ISSUE-2-load-after-view.md
상황이어 쓰는 구조나눈 구조
이슈가 하나 더 들어오면기존 문서에 이어 쓴다tickets에 파일 하나를 추가한다
지금 동작을 알려면두 이슈의 내용이 섞인 문서를 읽는다README 하나를 읽는다
새 수용조건 번호AC-9 (앞 이슈에 이어서)ISSUE-2 AC-1

다음 작업자와 AI는 README 하나만 읽으면 지금 동작을 안다.

새 용어

  • AI-DLC: AWS가 제안한 AI 중심 개발 흐름. 사람이 의도를 정하고, AI가 요구사항, 설계, 작업 단위를 문서로 만든 뒤 구현한다. 단계마다 사람이 확인한다.
  • 수용조건(AC, Acceptance Criteria): 이 동작이면 끝났다고 보는 기준. 테스트 이름에 번호를 붙여 동작과 테스트를 잇기도 한다.
  • bolt(B): AI-DLC의 작업 단위. 여기서는 커밋 하나에 대응하는 작업으로 쓴다.
  • 담당 경로: 기능 README frontmatter에 적는, 그 기능이 맡는 코드 경로 목록.
더 깊이

검토한 다른 안.

안쓰지 않은 이유
화면 주소별 폴더기능 하나가 여러 화면에 걸친다. 화면이 없는 작업은 둘 곳이 없다.
기능 아래 이슈별 폴더이슈끼리 섞이지는 않지만, 지금 동작을 알려면 이슈 폴더를 전부 읽어야 한다. AI가 작업마다 읽는 문서라 분량이 늘면 안 된다.

언제 무엇을 고치나.

시점READMEdecisionstickets
이슈 시작읽기만 한다읽고, 판단이 생기면 추가한다새로 만든다
작업마다동작을 바꾼 커밋에서 고친다판단이 생기면 추가한다작업 목록을 체크한다
이슈가 끝난 뒤--고치지 않는다
스펙만 먼저 머지하는 큰 이슈구현 MR에서 고친다판단이 생기면 추가한다먼저 머지한다

스펙을 먼저 머지할 때 README를 같이 고치면 아직 구현하지 않은 동작이 지금 동작 문서에 들어간다. 그래서 README만 구현 MR로 미룬다.

번호 규칙. 새 수용조건과 판단은 ISSUE-2 AC-1, ISSUE-2 D-1처럼 이슈 번호를 붙인다. 두 사람이 같은 기능을 동시에 작업해도 번호가 겹치지 않는다. 작업 번호는 이슈마다 B1부터 시작해 커밋 메시지와 맞춘다. 테스트 이름이 이미 쓰고 있는 기존 AC-n은 그대로 둔다.

폴더 찾기. README frontmatter에 담당 경로를 적는다.

---
code:
  - src/share/utils/log
  - src/share/components/LogReporter.tsx
---
상황어디에 쓰나
바꿀 파일이 한 기능의 담당 경로에 속함그 기능 폴더
여러 기능에 걸침바꿀 파일이 가장 많은 기능 폴더에 기록 파일 하나. 나머지 기능은 README만 고친다
어느 담당 경로에도 없음사람이 새 기능 폴더 이름을 정한다
한 기능이 너무 커짐같은 층위의 기능 폴더로 나눈다

두 기능이 같은 경로를 맡지 않는지는 문서 빌드에서 검사할 계획이다. 사람이 판단하는 때는 새 기능 폴더 이름을 정할 때와 커진 기능을 나눌 때뿐이다.

README가 낡지 않게 하기. 이 구조는 “동작을 바꾼 커밋에서 README도 고친다”는 규칙에 기댄다. 규칙이 지켜지려면 코드를 고치는 쪽이 README가 있다는 걸 알아야 한다. 그런데 지금은 문서가 코드를 가리킬 뿐이고, 코드 파일 쪽에서는 자기 문서가 있는지 알 수 없다.

코드에 문서 링크 주석을 넣지는 않는다. 담당 경로와 같은 정보를 두 곳에서 관리하게 되고 주석은 쉽게 낡는다. 대신 파일 경로로 담당 README를 찾는 스크립트를 하나 만들고, 아래 장치들이 모두 이 스크립트를 쓴다. 스크립트와 장치는 아직 설계만 했다.

시점장치
AI가 파일을 고치기 직전그 파일의 README와 decisions를 먼저 읽으라고 알리는 훅. 막지 않고, 세션마다 기능별로 한 번만 알린다
AI가 커밋하기 직전담당 파일은 바뀌었는데 README가 스테이징되지 않았으면 다시 알리는 훅
MR을 올릴 때담당 코드를 바꿨는데 README가 그대로면 경고. 사람이나 훅이 없는 다른 AI 도구가 고친 코드는 여기서 걸러진다
작업을 시작할 때README를 마지막으로 고친 커밋 이후 담당 경로의 변경을 찾아, 어긋나면 문서부터 맞춘다

경고는 MR을 막지 않는다. 동작이 바뀌지 않는 정리 MR에도 경고가 뜨므로, 막으면 작업자가 무시하거나 우회하게 된다.

AWS AI-DLC와 비교.

AWS 첫 버전AWS 지금 버전이 구조
작업 기록폴더 하나 (새 작업이 덮어씀)작업마다 새 폴더이슈마다 기록 파일
현재 상태-저장소 단위로 따로 둠기능 단위 README
현재 상태를 고치는 때-논의 중 (RFC #1055)동작을 바꾼 커밋에서

AWS도 작업 기록과 현재 상태를 나누는 방향으로 바뀌었다. 다만 현재 상태를 언제 고칠지는 아직 정하지 못했다.

아직 모르는 것.

  • README를 꾸준히 고치게 될지는 운영해 봐야 안다. 이슈 몇 건을 진행한 뒤 다시 점검한다.
  • 담당 경로 검사, 경로로 README 찾기, 훅, MR 경고는 설계만 했다.
  • Claude Code의 편집 직전(PreToolUse) 훅이 안내를 덧붙이는 출력(additionalContext)을 지원하는지 확인하지 않았다.
  • README의 수용조건 번호와 테스트 이름을 대조하는 검사를 둔다면, 테스트 이름에 번호가 없는 기존 수용조건을 어떻게 다룰지 정하지 않았다.

출처

Notes 피드로 가기