폴더 구성과 기술 선정

6편까지 저장소에는 README, Issue, CLAUDE.md가 생겼습니다. 이 글은 "정한다" 단계에서 사람이 정하지 않아도 되는 두 가지를 다룹니다. 폴더를 어떻게 나눌지, 어떤 언어와 도구로 만들지입니다. 둘 다 AI에게 맡기되, 사람이 길을 잃지 않을 최소한의 자리와 "정한 이유"를 남기는 규칙만 지킵니다. 다음 편 인터페이스를 정한다부터는 반대로 사람이 정해야 하는 것이 나옵니다.

핵심 요약

• 폴더 정리는 AI를 위해서가 아니라 내가 길을 잃지 않기 위해서입니다. 내가 만지는 파일은 README, CLAUDE.md, docs/ 세 종류뿐입니다.
• 기술 선정 기준은 인기도 최신도 아니고 "AI가 가장 익숙한 정석"입니다.
• 못 정하겠으면 AI에게 정하게 합니다. 대신 정한 이유를 docs/tech-choices.md에 반드시 적게 합니다.

정리는 AI를 위해서가 아니라, 내가 길을 잃지 않기 위해서

Claude Code는 폴더가 어지러워도 파일을 찾아냅니다. 정리가 필요한 쪽은 사람입니다. 어제 AI가 만든 파일이 어디 있는지, 내가 고쳐도 되는 파일이 무엇인지 모르면 대화가 막힙니다. 그래서 규칙은 단순합니다. 사람이 손대는 파일은 세 종류로 제한합니다.

1. README.md. 무엇인가와 완료 기준.
2. CLAUDE.md. AI와의 약속.
3. docs/ 안의 문서. 기술을 고른 이유, 인터페이스, 출력 형태.

나머지, 특히 src/ 안의 코드는 열지 않습니다. 보고 싶으면 AI에게 설명을 시킵니다. 우리 4주차 교재의 표준 구조(CLAUDE.md, docs/, src/, data/, tests/, .gitignore, .env.example, README.md)를 그대로 쓰되, 이 구조를 만드는 것도 AI에게 시킵니다. "이 구조로 폴더를 만들고 각 폴더의 용도를 README에 정리해 줘" 한 줄이면 됩니다. 프로젝트 하나가 폴더 하나라는 원칙도 지킵니다. 한 폴더에 여러 도구를 섞으면 CLAUDE.md의 약속이 서로 부딪힙니다.

개발자가 아닌 사람을 위한 기술 선정 기준

"파이썬으로 할까 자바스크립트로 할까"를 여러분이 고민할 필요는 없습니다. 다만 AI에게 고르게 할 때 기준은 줘야 합니다. 개발자가 아닌 사람에게 맞는 기준은 세 가지입니다.

• 내가 나중에 AI에게 설명을 들었을 때 이해할 수 있는가. 도구가 단순할수록 설명도 단순합니다.
• 무료로 시작할 수 있는가. 우리 수업의 상담 녹음 변환기 실습도 "무료로 쓸 수 있는 방법으로"가 제약이었습니다.
• 내 컴퓨터(윈도우든 맥이든)에서 그대로 돌아가는가. 이관은 7주차 별첨 주제일 만큼 별개의 일이라, 처음부터 한쪽에서만 도는 것은 피합니다.

성능이나 확장성은 이 단계의 기준이 아닙니다. 사용자가 여러분 한 명인 도구에 그런 기준을 들이대면 그림이 작아집니다.

"인기"도 "최신"도 아니고 "AI가 가장 익숙한 것"

기술을 고를 때 가장 흔한 실수는 유튜브에서 본 최신 도구를 고르는 것입니다. AI는 학습 데이터가 많은 기술을 잘 다룹니다. 오래 쓰여 자료가 많고 정석으로 자리 잡은 기술일수록 AI가 만드는 코드의 오류가 적고, 막혔을 때 스스로 고칠 확률도 높습니다. 최신 도구는 AI가 잘 모르는 부분에서 그럴듯한 오답을 만들고, 여러분은 그것을 판별할 수 없습니다. 그래서 기준은 "AI가 가장 익숙한 정석"입니다. 우리 2주차 교재에서 스킬, MCP, 서브에이전트 같은 확장 도구를 "아직 설치하지 마라"고 하는 것도 같은 이유입니다. 새롭고 강력해 보이는 것은 오류의 원인이 되기 쉽고, 필요한 시점은 나중에 옵니다.

못 정하겠으면 AI에게 정하게 한다

기준을 줬으면 선택은 AI에게 넘깁니다. plan 모드(Shift+Tab)에서 이렇게 시킵니다.

README.md와 docs/를 읽고 이 도구를 만들 기술을 골라 줘. 기준은 세 가지야.
1. 네가 가장 익숙하고 자료가 많은 정석일 것
2. 무료로 시작할 수 있을 것
3. 윈도우와 맥에서 모두 돌아갈 것
후보를 2개 이상 비교하고 하나를 추천해. 아직 설치하거나 만들지 마.

돌아온 답에서 여러분이 볼 것은 기술 이름이 아니라 비교의 이유입니다. "자료가 많다", "설치가 한 줄이다", "무료 한도가 충분하다" 같은 이유가 세 기준에 맞으면 승인합니다. 이름을 하나도 몰라도 됩니다. 이름을 모른다는 것이 불안하면 "각 후보를 비개발자에게 한 줄로 설명해 줘"를 덧붙이십시오.

단, "정한 이유"는 반드시 적게 한다

승인했으면 마지막 한 단계가 있습니다. 왜 그것을 골랐는지를 파일로 남기게 하는 것입니다.

방금 고른 기술과 그 이유, 탈락한 후보와 탈락 이유를 docs/tech-choices.md에 적어 줘.
날짜도 함께. 그다음 커밋하고 푸시해 줘.

이 파일이 없으면 석 달 뒤 "왜 이걸 썼지"라는 질문에 아무도 답하지 못합니다. AI도 새 세션에서는 모릅니다. 반대로 이 파일이 있으면 나중에 기술을 바꿀 때 "그때 이 이유로 골랐는데 지금은 조건이 달라졌다"고 판단할 수 있습니다. 우리 수업에서 작업 완료마다 목적, 변경 파일, 명령, 결과, 다음 작업 다섯 요소를 기록하게 하는 것과 같은 습관입니다. 결정에는 이유가 붙어 있어야 결정입니다.

해 보기

저장소에서 Claude Code를 켜고 세 가지를 순서대로 시키십시오. 첫째, 표준 구조로 폴더를 만들고 README에 용도를 정리하게 합니다. 둘째, plan 모드에서 위의 기술 선정 요청을 던지고 이유를 읽고 승인합니다. 셋째, docs/tech-choices.md를 쓰게 하고 커밋, 푸시합니다. 증거는 GitHub에서 보이는 docs/tech-choices.md 화면입니다. 아직 코드는 한 줄도 없어야 정상입니다.

정리

• 사람이 만지는 파일은 README, CLAUDE.md, docs/ 세 종류이고 src/는 열지 않습니다.
• 기준은 이해 가능, 무료 시작, 양쪽 OS에서 실행입니다.
• 기술은 AI가 가장 익숙한 정석으로, 선택은 AI에게 넘깁니다.
• 정한 이유는 docs/tech-choices.md에 날짜와 함께 남깁니다.

자주 묻는 질문