📌 이 글은 제가 AI 여러 개(Claude Code, Codex)와 일하면서 정착한 "폴더 하나에 프로젝트 하나, 요구사항 + 백로그 CLI" 방식을 정리한 것입니다. 개발자가 아니어도 따라 할 수 있는 수준이에요. 결론만 궁금하시면 맨 아래 최종 요약으로 가셔도 됩니다.
지난 글에서 내가 꾸민 Claude 환경과 기본 상태를 같은 과제로 붙여 봤죠. 그 실험에서 의외로 눈에 띈 게 하나 있었어요. "요구사항 파일과 백로그 파일이 있느냐"가 AI의 일하는 방식을 꽤 크게 바꾸더라고요. 오늘은 그 파일들을 어떻게 쓰고 있는지 이야기해 볼게요.
왜 이런 규칙이 필요했나?
퇴근 후에 AI랑 일하다 보면 이런 일이 생겨요.
- 🧠 세션이 바뀌면 AI가 다 잊는다: 어제 어디까지 했는지, 왜 그렇게 정했는지 다시 설명해야 해요.
- 📂 프로젝트가 섞인다: 주식 봇 얘기하다가 블로그 파일을 건드리는 식의 사고가 날 수 있어요.
- 🤝 AI가 하나가 아니다: Claude가 한도를 다 쓰면 Codex로 이어서 일하는데, 둘이 같은 기준을 봐야 하죠.
그래서 정한 답은 단순해요. "기억은 AI 말고 파일에 남긴다."
1단계: 프로젝트마다 폴더 하나
AI랑 하는 작업은 전부 AI_Workspace라는 폴더 하나에 모으고, 그 안에 프로젝트마다 하위 폴더를 하나씩 둡니다. 규칙은 세 줄이에요.
- 📁 세션은 맨 위 폴더가 아니라 해당 프로젝트 폴더에서 시작한다.
- 🚧 현재 프로젝트 폴더 밖의 파일은 고치지 않는다. 다른 프로젝트를 고쳐야 하면 먼저 나한테 묻는다.
- 🆕 새 프로젝트는 스크립트 하나로 만든다.
새 프로젝트 스크립트(new-project.sh)는 진짜 별거 없어요. 뼈대 폴더(_template)를 복사하고 git 저장소를 만들어 줄 뿐입니다.
💡 AGENTS.md와 CLAUDE.md를 나눈 이유: AGENTS.md는 Claude, Codex 등 모든 AI가 읽는 공통 규칙이고, CLAUDE.md는 Claude에만 해당하는 규칙이에요. CLAUDE.md 첫 줄에 @AGENTS.md라고 적어 두면 Claude도 공통 규칙을 같이 읽어요. 규칙을 두 군데에 똑같이 쓸 필요가 없죠.
2단계: 시작은 항상 요구사항 → 백로그 → CLI
폴더를 만든 다음엔 바로 기능을 만들지 않고, 모든 프로젝트를 같은 순서로 시작해요.
① requirements.md: 무엇을 만들고, 무엇을 안 하는지
만들 것, 만들지 않을 것, 완료 기준을 적어요. 제일 중요한 건 "안 하는 것"이에요. 예를 들어 이 블로그 프로젝트에는 "글 삭제, 요청 없는 글 수정·공개, 비밀번호 입력은 하지 않는다"고 적혀 있어요.
그리고 기능을 바꿀 때마다 이 파일도 같이 고치게 했어요. 기준은 "대화 기록이 없어도 이 파일만 보고 똑같이 다시 만들 수 있을 만큼"이에요.
② backlog.json: 할 일 목록이자 진행 상황
할 일을 전부 여기에 등록하고, 상태(할 일·하는 중·완료·막힘)도 여기서만 바꿔요. 작업 하나는 이렇게 생겼어요. 실제로 쓰고 있는 AI 사용량 위젯 프로젝트의 작업 하나예요.
핵심은 done_when(완료 기준)이에요. "서버 만들기"가 아니라 "브라우저에서 이 화면이 뜨면 끝"처럼 눈으로 확인할 수 있게 적어 두면, AI가 어설프게 "다 했습니다" 하고 넘어가는 일이 줄어요. depends_on은 먼저 끝나야 하는 작업이에요.
여기서 "할 일 목록도 그냥 md로 쓰면 안 돼?" 하는 생각이 들 수 있어요. 저도 처음엔 그랬어요. 쉽게 비유하면 이래요.
- md(마크다운) = 사람에게 남기는 메모예요. "초안 끝남!"이라고 쓰든 "✅"를 붙이든, 읽는 사람은 다 알아들어요.
- json = 칸이 정해진 주문서예요. 엑셀처럼 "이름 칸", "상태 칸"이 있고, 상태 칸에는 정해진 말(예:
todo,done)만 써요. 그래서 기계가 헷갈리지 않아요.
같은 할 일 두 개를 양쪽으로 적어 보면 차이가 보여요(설명용 가짜 작업이에요).
📝 md로 쓰면
## 할 일
- 블로그 초안 쓰기 → 끝남!
- 미리보기 캡처 (초안 끝나면)📋 json으로 쓰면
[
{"id": "T01",
"title": "블로그 초안 쓰기",
"status": "done"},
{"id": "T02",
"title": "미리보기 캡처",
"status": "todo",
"depends_on": ["T01"]}
]사람 눈엔 둘 다 같은 말이죠. 그런데 프로그램 눈에는 md의 "끝남!", "완료", "✅"가 전부 다른 글자예요. json은 status 칸에 done이라고만 쓰니까 "몇 개 끝났어?"를 정확히 셀 수 있어요.
제가 들었던 강의(멀티캠퍼스 「개발자를 위한 바이브코딩 마스터 with 클로드코드」, 강사 곽은철(개발자F)님)에서도 같은 얘기를 했어요. 마크다운은 사람 몫이 조금 더 큰 문서라서 사람이 꼭 읽고 검토하고, json은 AI·도구 몫이 조금 더 큰 문서라서 손대지 않고 도구로만 바꾼다고요. 그래서 요구사항(md)에서 시작해 backlog.json, 그걸 고치는 도구 순서로 만든다는 거예요.
저한테 이게 진짜 쓸모 있었던 순간은 프로젝트가 여러 개로 늘었을 때예요. 여러 가게의 주문서를 사장님 화면 하나에 모아 보는 것처럼, 각 프로젝트 폴더의 backlog.json을 10분마다 모아서 전체 현황판을 자동으로 만들게 했거든요. 주문서 양식이 다 같으니까 가능한 일이에요.
단점도 있어요. json은 쉼표 하나만 빠져도 기계가 통째로 못 읽어요. 그래서 아무나 장부에 손으로 쓰지 않고, 정해진 접수 창구를 거치게 했어요. 그 창구가 바로 다음에 나오는 backlog.py예요. 이렇게 명령어 한 줄로 쓰는 작은 프로그램을 CLI라고 불러요.
③ backlog.py: 백로그는 CLI로만 고친다
백로그는 json 파일이지만, AI가 직접 열어 고치지 않고 작은 명령어 도구(CLI) backlog.py로만 고치게 했어요. 처음엔 저도 "굳이?" 싶었는데, AI 여러 명이 같이 일할 때 진가가 나와요. 그림으로 보는 게 빨라요.
할 일을 작게 나누고 "이건 저게 끝나야 시작" 하는 순서만 적어 두면, 기다릴 게 없는 작업은 여러 AI에게 동시에 맡길 수 있어요. 순서를 어기려 하면 CLI가 거절해요.
누가 어떤 일을 잡았는지도 백로그에 보여요. 다만 정직하게 말하면, "doing인 일은 건드리지 않기"는 CLI가 강제하는 게 아니라 약속이에요. 규칙 파일에 적어 두고, AI가 목록을 보고 지키는 방식이에요.
제 환경에서는 메인 Claude가 겹치지 않는 작업을 골라 구현 담당 에이전트들에게 나눠 주고, 각자 따로 떼어 낸 폴더 사본에서 일하게 해요. 원본에 반영하는 건 메인 하나뿐이라 서로 파일을 덮어쓸 일이 없어요.
쓰는 법은 명령 한 줄씩이에요.
- 🧳 파이썬 기본 기능만 사용: 300줄 정도인 파일 하나라서, 새 프로젝트에는 다른 폴더 것을 그대로 복사해 써요.
그다음부터는 기능을 이 작업 단위로 하나씩 만들고, 동작하는 중간 결과를 최대한 빨리 보여 달라고 해요. 위 M02처럼 "샘플 데이터로라도 화면부터 띄우기"가 앞쪽에 오는 이유예요.
3단계: 써 보니 이게 좋더라
제일 많이 쓴 건 미국주식 모니터링 봇(Stock_Analyzer)이에요. 10월 4일에 요구사항부터 쓰기 시작해서 11일 동안 작업 137개 중 128개를 끝냈어요.
- 🔁 세션이 바뀌어도 이어진다: 새 세션에 "backlog 보고 이어서 해"라고만 하면 돼요. 길게 설명할 필요가 없어졌어요.
- 🤝 다른 AI도 같은 기준: Claude 한도가 바닥나서 Codex로 넘어가도 같은 AGENTS.md, 같은 backlog를 봐요.
- 📊 진행률이 보인다: "얼마나 남았지?"가 숫자로 나와요. 위 그래프도 각 폴더 backlog.json을 세기만 한 거예요.
삽질 두 개: 규칙을 적었는데 AI가 안 따랐다
① 규칙을 엉뚱한 곳에 적었다
처음엔 이 순서를 맨 위 폴더에서 연 세션에게만 말해 뒀어요. 그랬더니 그 세션의 메모리에만 저장돼서, 하위 폴더에서 연 세션은 이 규칙을 전혀 몰랐어요. 그래서 맨 위 폴더의 CLAUDE.md에 적었더니 해결됐어요. Claude Code는 상위 폴더의 CLAUDE.md도 자동으로 읽거든요.
② 규칙끼리 부딪혔다
지난 글의 실험에서 제 환경의 Claude에게 사람 없이 과제를 시켰는데, 1라운드에선 요구사항·백로그 흐름을 4번 모두 건너뛰었어요. 원인은 제가 써 둔 다른 규칙이었어요. "프로젝트가 최신 흐름과 다르면 바로 고치지 말고 사용자에게 먼저 물어라." 그런데 물어볼 사람이 없으니 그냥 넘어간 거죠.
2라운드에선 과제 폴더에 requirements.md와 backlog.json을 미리 넣어 뒀어요. 그랬더니 시험 운전까지 포함해 8번 모두 흐름을 따랐어요. 재밌는 건 아무것도 안 꾸민 기본 Claude Code도 똑같이 따랐다는 거예요.
💡 교훈: "이렇게 해라"는 규칙 문장보다 파일이 이미 있느냐가 더 셌어요. AI는 폴더에 있는 걸 보고 따라 해요. 그러니 새 프로젝트를 열면 요구사항과 백로그 파일부터 만들어 두는 게 제일 확실해요.
주의사항
⚠️ 규칙 파일은 약속이지 잠금장치가 아니에요. "폴더 밖은 안 고친다"는 AI가 읽고 지키는 규칙일 뿐, 기술적으로 막는 건 아니에요. 중요한 파일은 git으로 기록을 남겨 두세요.
⚠️ 규칙을 바꾸면 이유도 남기세요. 저는 흐름을 바꿀 때마다 WORKFLOW_HISTORY.md에 날짜·바꾼 것·이유를 적어요. 나중에 "왜 이렇게 했지?"를 AI도 저도 찾을 수 있게요.
마치며
거창한 프로젝트 관리 도구를 쓴 게 아니에요. 폴더 하나, 마크다운 파일 하나, json 파일 하나, 300줄 정도인 스크립트 하나가 전부예요. 그런데 이걸 쓰고 나서부터 "AI가 어제 일을 기억 못 해서" 생기는 스트레스가 확 줄었어요.
다음 글에서는 Claude 말고 다른 AI 비서, 메타 뮤즈를 열흘 동안 써 본 이야기를 해 볼게요. 잘된 것, 망한 것, 결국 Claude로 옮긴 것까지요.
최종 요약
✅ 결론만 보고 싶은 분
1. 프로젝트마다 폴더 하나. 세션은 그 폴더에서 열고, 폴더 밖은 고치지 않는다.
2. 공통 규칙은 AGENTS.md(모든 AI), Claude 전용은 CLAUDE.md(첫 줄 @AGENTS.md).
3. 시작 순서: requirements.md(안 하는 것 포함) → backlog.json(완료 기준 done_when) → backlog CLI → 작업 단위 구현.
4. backlog는 CLI로만: 순서(depends_on)를 적으면 기다릴 게 없는 일은 여러 AI가 동시에, 잡은 일은 doing으로 표시(이건 약속), 잠금·검사로 파일 보호.
5. 주식 봇 11일 동안 137개 중 128개 완료. 세션이 바뀌어도, Codex로 넘어가도 이어진다.
6. 교훈: 규칙 문장보다 파일이 이미 있느냐가 더 세다.
도움이 됐다면 공유 부탁드립니다! 질문은 댓글로 남겨주세요.
'AI 활용기' 카테고리의 다른 글
| 내 Claude Code 환경 vs 기본 상태, 같은 과제로 붙여 봤다｜서브에이전트 7개 중 일한 건 1개 (0) | 2026.10.16 |
|---|---|
| Claude Code에 Codex 리뷰어 붙이기｜헤르메스 없이 명령어 한 줄이면 됐다 (0) | 2026.10.14 |
| 로컬 LLM(Ollama gemma)으로 Claude 토큰 아끼기｜맥미니에 gemma4 올리고 Haiku랑 정확도 붙여 본 기록 (0) | 2026.10.13 |
| Claude Code에 서브에이전트 붙이기｜혼자 다 하던 AI에게 팀을 만들어 줬습니다 (0) | 2026.10.12 |
| 한국에서 메타 뮤즈(Muse) 가입하기 — 완전 정복 가이드 (0) | 2026.10.07 |
