프로젝트를 만들고 굴리고 보관하는 방식

동시에 굴리는 프로젝트가 스무 개를 넘어가면서, 프로젝트마다 다르게 하던 것들을 하나씩 같은 절차로 굳혔습니다. 새로 만드는 날 무엇을 놓는지, 진행 중에 무엇을 어디에 적는지, 끝나면 어떻게 치우는지가 정해져 있어야 다음 프로젝트로 넘어갈 때 머리를 비울 수 있습니다. 이 글은 그 절차를 순서대로 적은 것입니다.

디렉터리 하나가 프로젝트 하나

모든 프로젝트는 한 드라이브의 한 폴더 아래에 <소속>_<이름> 으로 놓습니다. 소속은 발주처나 회사, 개인 이름입니다. 폴더 목록만 훑어도 누구 일인지 보이고, 뒤에서 이야기할 보드와 아카이브 도구가 이 이름을 그대로 프로젝트 이름으로 씁니다.

D:\Project\
  ClientA_Video_Codec_Check\     발주처_과제명
  ClientB_USV_System\
  Company_Labeling_Service\      회사_서비스명
  Personal_Portfolio_Site\       개인_프로젝트명

만드는 날 하는 일은 정해져 있습니다. git init 을 하고, 아래 세 파일을 놓고, 파이썬 프로젝트면 uv venv 로 가상환경을 만듭니다. 원격 저장소는 처음부터 두지 않습니다. 사내 GitLab 에 그룹을 만들 만큼 일이 커지면 그때 연결합니다.

지침·메모리·태스크 세 벌

프로젝트 루트에는 사람과 AI 도구가 함께 읽는 파일 세 벌이 있습니다. 역할이 겹치지 않게 나눠 두는 것이 요점입니다.

지침에는 "무엇을 하라" 를, 메모리에는 "왜 그렇게 정했나" 를 적습니다. 코드나 git 이력을 보면 알 수 있는 것은 적지 않습니다. 메모리 파일 하나는 이런 모양입니다.

---
name: dev-image-glibc
description: 개발 컨테이너 이미지는 alpine 이 아니라 glibc 기반이어야 하는 이유
metadata:
  type: project
---

alpine(musl) 이미지에서는 JSX 컴파일러가 로드되지 않는다.
**Why:** 네이티브 바이너리가 glibc 를 전제한다.
**How to apply:** 베이스 이미지를 node:24-slim 으로 두고 alpine 으로 되돌리지 않는다.

세 파일 중 task.md 만 저장소에 올립니다. 지침과 메모리에는 내부 주소나 자격 증명 위치, 운영 중 밟은 함정 같은 것이 들어가므로 .gitignore 에 넣습니다. 공유 저장소에 섞이면 곤란한 것들입니다.

메일과 회의도 프로젝트 안에

코드만 프로젝트에 두면 정작 판단의 근거는 사람 머릿속에만 남습니다. 왜 이 사양이 되었는지, 무엇을 언제 회신했는지는 메일과 회의에 있는데 그것이 메일함과 녹음 파일에 흩어져 있으면 몇 달 뒤에는 아무도 복원하지 못합니다. 그래서 프로젝트 루트를 문서·메일·회의록·리소스·태스크·메모리·지침이 있는 자리로 두고, 코드베이스는 그 아래 서브디렉터리로 내렸습니다.

ClientA_Video_Codec_Check\
  CLAUDE.md           프로젝트 지침
  task.md             남은 일 · 끝난 일
  .claude\memory\      결정의 이유와 함정
  mail\               주고받은 메일(초안 · 발송본)
  meetings\           녹음 전사 · 회의록(액션아이템)
  docs\               산출물 문서 · 제출본
  resources\          받은 자료 · 규격 · 샘플
  codec-check\        코드베이스(서브디렉터리)

메일은 보내고 끝내지 않고 초안부터 발송본까지 프로젝트 안에 남깁니다. 초안을 파일로 쓰면 문구를 고친 이력이 남고, 보낸 뒤에는 같은 파일이 "언제 무엇을 약속했는지" 의 근거가 됩니다. 회신에서 새 요구사항이 나오면 그 자리에서 task.md 에 한 줄로 옮깁니다.

회의는 녹음해 두고 직접 훈련한 온디바이스 전사 모델로 받아씁니다. 외부 서비스에 올릴 수 없는 내용이라 장비 안에서 도는 모델을 쓰고, 도메인 용어와 회의실 녹음 조건에 맞춰 따로 훈련해 두었습니다. 전사 결과를 그대로 두면 아무도 다시 읽지 않으므로, 결정 사항과 액션아이템만 추려 회의록으로 정리해 보관합니다.

판단 기준은 "이 프로젝트를 처음 여는 사람이 폴더만 보고 따라올 수 있는가" 입니다. 내가 기억하고 있어서 안 적어 둔 것이 보이면 그것부터 적습니다.

파이썬은 uv, 서비스는 Docker Compose

• 파이썬은 시스템 인터프리터를 직접 부르지 않습니다. uv venv 로 만든 가상환경에서 uv run 으로만 실행하고, 의존성은 pyproject.toml 과 잠금 파일로 고정합니다. 버전이 섞여 생기는 ImportError 를 겪지 않으려는 것입니다.
• 서버가 붙는 프로젝트는 처음부터 compose.yml 을 둡니다. 개발용과 빌드용 서비스를 나눠 두면 다른 PC 에서 열어도 같은 환경이 됩니다.
• 일회성 도구는 uvx 로 부릅니다. 프로젝트에 설치하지 않습니다.

태스크는 파일로, 보드는 파일을 읽는다

진행 상황을 따로 입력하는 도구는 오래가지 않았습니다. 그래서 상태는 프로젝트 안의 task.md 에만 적고, 사내 서버에서 도는 보드가 프로젝트 폴더를 60초 주기로 읽어 한 화면에 모읍니다. 보드는 같은 방식으로 AI 도구의 작업 기록도 읽어, 프로젝트별 최근 작업과 토큰 사용량을 함께 보여 줍니다.

# Personal_Portfolio_Site - 남은 작업 및 일정
> 기준일: 2026-09-08

## 완료
- [x] 좁은 화면 메뉴를 사이드바로 전환 (2026-09-08)

## 진행 중·대기
- [/] 머메이드 순서도 자체 렌더러
- [ ] Solid 정식 2.0 배포 시 RC 고정 정리

형식은 일부러 좁게 잡았습니다. 체크박스는 대기·진행 중·완료·취소 네 가지뿐이고, 항목은 한 줄입니다. 카드에 한 줄로 잘려 보이기 때문이기도 하지만, 한 줄로 못 적는 항목은 아직 할 일이 아니라는 신호이기도 합니다. 갱신은 세션 끝에 몰아서 하지 않고 상태가 바뀌는 순간에 합니다. 몰아서 쓰면 빠뜨립니다.

AI 도구와 나누는 일

설계와 판단은 사람이 하고, 반복되는 작성·조사·검토는 AI 도구에 맡깁니다. 나누는 기준은 "틀렸을 때 내가 알아챌 수 있는가" 입니다. 알아챌 수 있는 일은 맡기고, 없는 일은 직접 합니다. 도구가 한 일은 빌드까지 돌려 확인합니다. 타입 검사와 린트가 지나가도 화면은 열어 봐야 하고, 정적 산출물이면 하이드레이션까지 걸린 상태에서 콘솔을 봅니다.

세션 제목에는 프로젝트 접두를 붙입니다([개인 홈페이지] 처럼). 여러 프로젝트를 오갈 때 어느 세션이 어느 프로젝트인지 목록에서 바로 보이게 하려는 것이고, 보드가 세션을 프로젝트에 붙이는 근거이기도 합니다.

끝난 프로젝트는 압축해서 저장 장치로

끝난 프로젝트를 작업 드라이브에 그대로 두면 목록이 길어지고, 몇 달 뒤에는 어느 것이 최신인지 헷갈립니다. 그래서 종료하면 정해진 절차로 치웁니다. 손으로 하면 빠뜨리는 단계가 있어서 절차 자체를 도구로 만들어 두었습니다.

1. 가상환경·캐시·중간 빌드 산출물을 지웁니다. 실행 파일은 다시 만들기 어려운 것만 확인하고 남깁니다.
2. .git 은 git bundle 한 파일로 바꿉니다. 이력은 전부 살고 크기는 줄어듭니다.
3. <프로젝트명>_<날짜>.zip 으로 묶고, 압축을 다시 열어 파일 수가 맞는지 검증합니다.
4. 검증이 지나가면 원본 폴더를 지우고, 저장 장치의 카탈로그 문서에 항목(설명·크기·git 형태)을 올립니다.

복원은 반대입니다. 카탈로그에서 항목을 찾아 같은 이름의 폴더로 풀고, 묶음 파일이 있으면 git init 뒤에 되돌립니다. 지침 파일에는 복원 뒤 다시 설치해야 할 것(가상환경·의존성)이 적혀 있어서 그대로 따라가면 됩니다.

아직 손보는 것들

• 메모리가 쌓이면 낡은 것과 겹치는 것이 생깁니다. 주기적으로 병합하고 틀린 것을 지우는 과정을 아직 손으로 합니다.
• task.md 를 세션 끝에 몰아서 고치고 싶은 유혹은 사라지지 않습니다. 보드가 갱신 시각을 보여 주는 것이 그나마 억제 장치입니다.
• 지침 파일이 길어지면 매 세션의 맥락을 잡아먹습니다. 특정 작업에만 필요한 규약은 별도 스킬로 빼서 그 작업을 할 때만 읽게 옮기는 중입니다.