TL;DR
Claude Code 같은 AI 도구로 개발하다 보면 작업 맥락을 잃어버린다. Features 추적 시스템은 모든 기능을 문서로 추적하고, INDEX.md로 토큰을 50배 절약한다.
29개 기능 추적, 토큰 50배 절약, Git 히스토리 보존.
배경: daily_work_summary의 한계
처음엔 daily_work_summary/2025-10-15.md 형식으로 일별 작업 로그만 썼다.
# 2025-10-15
- 로그인 기능 수정
- 검색 버그 수정
- 캐싱 추가 시작
문제는 며칠 뒤였다:
- 기능 단위 추적 불가
- “검색 버그를 어떻게 고쳤더라?” → 여러 날짜 파일 뒤적임
- “캐싱 관련 커밋이 어디 있지?” → Git log 전체 검색
-
Claude 대화 스레드 관리 실패 + 병렬 작업의 혼란
Claude Code로 작업하다 보면 여러 기능을 병렬로 돌려야 효율이 좋다. 하나 시켜놓고 멍하니 기다릴 순 없으니까.
그런데 이러다 보니 퇴근 시간에 F001, F003, F006을 동시에 하다 멈추게 되고, 여러 맥락을 동시에 기억하려니 사람인 나도 과부하가 온다.
출근해서 “어디까지 했더라?” 파악하는 데만 매번 30분씩 날렸다.
- AI 토큰 낭비
- “지난주에 뭐했는지” 설명하려면 daily_log 5개 파일 읽어야 함
- 33개 기능 → 33개 README 전부 읽으면 15,000 토큰 소모
→ 기능 단위 추적 + 토큰 절약을 위해 Features 시스템 도입
해결 방법: Features 시스템
실제 사용 플로우
상황 1: 작업 중단할 때 (컴퓨터 꺼야 할 상황)
(F006 검색 기능 작업 중...)
나: /pause
AI: "F006 진행 상황 저장했습니다"
→ frontmatter에 현재 상태 기록
→ INDEX.md 업데이트
(컴퓨터 종료, 주말 지남...)
상황 2: 작업 재개할 때 (월요일 출근)
금요일에 F001, F003, F006 세 개를 동시에 하다 퇴근했다.
나: /resume
AI: "중단된 작업 3개:
- F001 사용자 인증 (90%, 테스트만 남음)
- F003 로깅 시스템 (50%, AOP 설정 중)
- F006 검색 최적화 (30%, 인덱스 설계 중)"
→ 30분 헤매던 시간이 0초로 ✅
상황 3: 작업 완료했을 때
나: /finish
AI: 자동으로 처리합니다:
1. Features 문서 업데이트 (status: DONE)
2. 작업일지 작성
3. Git 커밋
4. "이거 블로그 쓸만한가요?" 판단
결과: AI가 내 작업 맥락을 기억하고 관리해준다.
핵심 아이디어
“모든 기능 = 하나의 문서”
docs/features/
├── INDEX.md # 빠른 조회용 캐시
├── F001-user-auth/ # 기능별 폴더
│ ├── README.md # 작업 추적
│ ├── blog.md # 블로그 초안 (선택)
│ └── images/ # 스크린샷
│ ├── 01-before.png
│ └── 02-after.png
├── F002-api-refactoring/
└── F003-logging-system/
1. Frontmatter로 상태 관리
다른 방법들은 왜 안 썼나?
많은 프로젝트 관리 시스템들이 상태별로 폴더를 나눈다:
TODO/F001-user-auth.md
IN_PROGRESS/F001-user-auth.md
DONE/F001-user-auth.md
문제는 파일을 이동하면 Git 히스토리가 끊긴다는 점이다:
git log F001-user-auth.md→ “어? 방금 만든 파일인데요?”- Git이 “파일 삭제 + 새 파일 생성”으로 인식
- GitHub blame도 제대로 안 됨
해결: 파일은 그대로 두고 메타데이터만 변경
---
id: F001
title: 사용자 인증 시스템
status: DONE # TODO → IN_PROGRESS → DONE
priority: HIGH
created: 2025-10-18 KST
completed: 2025-10-21 KST
elapsed_hours: 16
labels: [feature, backend, security]
---
# 사용자 인증 시스템
## ✅ 완료된 작업
- [x] JWT 토큰 발급
- [x] 리프레시 토큰 구현
- [x] 권한 체크 미들웨어
## 🔗 관련 커밋
- `8356a91` - feat: JWT 인증 구현
장점:
git log docs/features/F001-user-auth/README.md하면 전체 과정을 추적할 수 있다- GitHub에서 blame도 정상 작동한다
- 폴더 이동 없이 상태만 바뀐다
2. INDEX.md로 토큰 절약
50개 기능 파일을 다 읽으면 수만 토큰을 낭비한다. 대신 요약본 하나만 읽는다.
---
last_updated: 2025-11-01 20:00 KST
auto_generated: true
---
## 📊 요약
- **TODO**: 8개
- **IN_PROGRESS**: 2개
- **DONE**: 21개
## 🚀 IN_PROGRESS
### [F006](F006-search-optimization/) 검색 성능 최적화
- **시작**: 2025-10-30 05:00 KST
- **진행률**: 30%
## 📋 TODO
### [F023](F023-caching-layer/) 캐싱 레이어 추가
- **예상 시간**: 2-3시간
- **주제**: Redis 캐싱 구현
효과:
- INDEX.md 읽기: ~300 토큰
- 전체 파일 읽기: ~15,000 토큰
- 50배 절약!
3. 슬래시 커맨드로 완전 자동화
/finish - 8단계 자동 프로세스
1. 변경사항 확인
2. 코드 정리 (디버깅 로그 제거)
3. Features 시스템 업데이트 ⭐
→ frontmatter status: DONE
→ completed: [현재시각]
→ INDEX.md 업데이트
4. 작업일지 작성
5. Git 커밋
6. Features 파일에 커밋 해시 기록 ⭐
7. 최종 보고
/pause & /resume - 작업 중단/재개
/pause
→ 현재 IN_PROGRESS 작업들의 상태 저장
→ INDEX.md 업데이트
(다음날)
/resume
→ INDEX.md만 읽어서 중단된 작업 확인 (토큰 절약)
→ 사용자가 선택하면 해당 feature 파일 읽기
→ 작업 재개
배운 점
1. “대화 맥락 > Git Log”
문제: 동시에 여러 기능을 개발 중일 때
git log --since="1 hour ago"
→ F001, F002, F003 커밋이 섞여 있음
→ AI가 "어떤 거 작업하셨나요?" 물어봄
해결: 같은 대화 스레드면 AI가 이미 알고 있다!
사용자: (F003 작업 중...)
사용자: /finish
AI:
1. 대화 맥락 확인: "이 세션에서 F003 작업함" ✅
2. 즉시: "F003 완료 처리할까요?"
정보 우선순위:
- Features/README.md (최우선) - 이미 구조화된 맥락
- 작업일지 (보완) - 디테일, 시행착오
- Git diff (코드 예시) - 실제 변경사항
→ Git log는 새 스레드에서만 fallback으로 사용한다!
2. “AI는 도구가 아니라 팀원”
AI를 단순 코딩 보조로만 쓰지 말고, AI가 따라갈 워크플로우를 설계하자.
❌ "AI야, 이거 해줘" (매번 설명)
✅ "AI야, F003 작업 시작" (시스템이 알아서 컨텍스트 로드)
3. “파일 이동은 Git의 적”
상태를 바꿀 때 파일을 todo/ → in-progress/ → done/으로 옮기면:
git log --follow필요- GitHub blame 깨짐
- 히스토리 추적 어려움
→ Frontmatter 메타데이터로 해결!
4. “토큰은 돈”
50개 파일을 매번 읽으면:
- 느리다
- 비싸다
- 컨텍스트가 꽉 찬다
→ INDEX.md 캐시로 50배 절약
5. “모든 프로젝트에 표준화”
Features 시스템을 모든 프로젝트의 필수 표준으로 확립했다.
# ~/.claude/CLAUDE.md (전역 설정)
## 📋 Features 추적 시스템 (모든 프로젝트 표준)
### 핵심 원칙
**모든 작업은 Feature로 추적된다.**
- ✅ 새 기능 개발 → Feature
- ✅ 버그 수정 → Feature
- ✅ 리팩토링 → Feature
- ✅ 문서 작성 → Feature
- ❌ "Features 추적 안 하는 작업"은 존재하지 않음
자동 설정 유도:
# 새 프로젝트에서 /finish 실행 시
AI:
1. docs/features/ 폴더 확인
2. 없으면:
┌────────────────────────────────────────┐
│ ⚠️ Features 추적 시스템이 없습니다. │
│ │
│ 지금 설정할까요? │
│ │
│ 생성 파일: │
│ - docs/features/INDEX.md │
│ - docs/features/F001-[현재작업]/ │
│ │
│ [Y/n] │
└────────────────────────────────────────┘
주의할 점
1. INDEX.md는 “캐시”
- 개별 파일이 원본 (Source of Truth)
- INDEX.md가 꼬이면 재생성 가능
- 자동 업데이트 필수
2. Features 남발 방지 - 관련 Feature 검색
문제: 작은 버그 수정마다 새 Feature를 만들면?
F005: 검색 기능 구현
F006: 검색 버그 수정
F007: 검색 성능 개선
F008: 검색 UI 개선
→ Feature가 너무 많아진다!
해결: /finish 실행 시 관련 Feature를 자동으로 검색한다
사용자: "검색 버그 수정했어. /finish"
AI:
1. 대화 맥락에서 키워드 추출: "검색", "버그"
2. INDEX.md 검색 → F005 발견
3. 사용자에게 선택 제안:
┌─────────────────────────────────────────┐
│ F005와 관련된 작업으로 보입니다. │
│ │
│ A) F005에 이어서 작업 │
│ - status: DONE → IN_PROGRESS │
│ - "🐛 추가 수정사항 (2차)" 섹션 추가 │
│ │
│ B) 새 Feature 생성 (F006) │
│ │
│ 선택: [A/B] │
└─────────────────────────────────────────┘
A 선택 시: Feature 재개
---
id: F005
status: IN_PROGRESS # DONE → IN_PROGRESS 변경
resumed: 2025-10-31 12:00 KST
completed: 2025-10-31 10:30 KST # 첫 완료 시각 유지
---
## 🐛 추가 수정사항 (2차 - 2025-10-31)
### 배경
F005 작업 중 검색 버그 발견...
### 수정 내용
- 특수문자 이스케이프 처리
- 검색 결과 정렬 로직 개선
### 관련 커밋
- `abc1234` - fix: 검색 특수문자 처리
→ 관련 작업이 한 곳에 모인다!
실제 프로젝트 사례
이 시스템을 실제로 적용한 교육 관리 시스템 프로젝트에서:
정량적 효과
- 29개 기능 추적 (TODO 8개, IN_PROGRESS 2개, DONE 21개)
- 토큰 50배 절약 (INDEX.md 캐시 덕분)
정성적 효과
1. 컨텍스트 보존
새 대화 시작:
"F006 작업 이어서 해줘"
AI가 INDEX.md 읽음 → F006 파일 읽음 → 바로 재개
2. Git 히스토리 완벽 보존
$ git log docs/features/F001-user-auth/README.md
→ 3일간 12개 커밋 전부 추적 가능
3. 업계 비교
| 도구 | 특징 | Features 시스템 |
|---|---|---|
| Claude Task Master | MCP 기반, 36개 도구 | ✅ 마크다운으로 더 간단 |
| GitHub Issues | 프로젝트 단위 | ✅ 기능 단위 세분화 |
| Notion | 수동 관리 | ✅ AI 자동화 |
정리
Features 추적 시스템은:
- 컨텍스트 보존 - AI가 작업 맥락을 잃지 않게
- 토큰 절약 - INDEX.md로 50배 효율 향상
- Git 히스토리 보존 - Frontmatter로 상태 관리
- 전역 표준화 - 모든 프로젝트에 적용
AI 코딩 도구를 쓴다면, AI가 따라갈 수 있는 워크플로우를 먼저 만들자.
다음 글: Features 시스템을 활용한 블로그 자동화에 관심이 있다면 /blog 명령어 - 개발 블로그 작성 시간을 83% 줄인 방법을 읽어보자.
Comments