todo-management

name	todo-management
description	이슈 해결을 위한 구조화된 문서 작성 및 관리. 작업 시작 전 todo-template-fix.md 기반 문서 생성, 작업 시작 시 프로젝트 전체 구조를 확인, 진행 중 5W1H 육하원칙 준수하여 context-free하게 작성, checkbox로 진행 추적. 이슈 작업을 시작하거나, TODO 문서를 작성/update할 때, 또는 작업 완료 후 문서화할 때 사용.
version	1.0.0

TODO management

1. TODO 5W1H 육하원칙 준수

모든 기술 문서는 항상 여섯 항목(Who/When/Where/How/What/Why)에 대해서 명확하게 서술되어야 한다.

1-1. TODO 5W1H 육하원칙 준수: 5W1H 육하원칙 체크리스트

모든 기술 결정/구현을 문서화할 때 다음 확인

• Who: 누가 하는가? (주체/대상)
• When: 언제 하는가?
• Where: 어디서 하는가? (환경/위치/파일위치)
• What: 무엇을 하는가?
• How: 어떻게 하는가? (메커니즘)
• Why: 왜 하는가? (목적/이유/의도)

1-2. TODO 5W1H 육하원칙 준수: Examples

todo-5w1h-examples.md 참고

2. TODO Context-Free Key-Items 준수

todo 파일의 핵심 항목을 준수해서 작성해야 한다. LLM 이 context 없이도 todo 파일만 읽어서 독립적으로 이해 가능.

2-1. TODO Context-Free Key-Items 준수: 핵심 작성 항목

2-1-1. 새 기능 추가 시 (feat) 항목

• 1. (사람이 작성하는 항목) 배경, 참고사항
  • 1-*. (사람이 작성하는 항목) 배경, 참고 로직/원칙/세부사항/구현의도
• 2. (사람이 작성하는 항목) 요구사항
  • 2-*. (사람이 작성하는 항목) 요구사항 기능 서술
    • 2--. (사람이 작성하는 항목) 이 기능을 구현하게되면 신경써야하는/확인해야하는 중요한 부분
    • 2--. (사람이 작성하는 항목) 우선적으로 참조할 파일
• 3. (AI가 작성하는 항목) 기존 코드/구현의 핵심내용들/의도들
• 4. (AI가 작성하는 항목) 생각한 수정 방안들
  • 4-*. (AI가 작성하는 항목) 처음에 생각한 코드 수정 방안들
• 5. (AI가 작성하는 항목) 최종 결정된 수정 방안 (AI 가 자동 진행하면 안되고 무조건/MUST 사람에게 선택/결정을 맡겨야 한다)
  • 5-*. (AI가 작성하는 항목) 여러 수정 방안들, 결정 이유
• 6. (AI가 작성하는 항목) 코드 수정 요약
  • 6-*. (AI가 작성하는 항목) 수정한 기능들
• 7. (AI가 작성하는 항목) 문제 해결에 참고한 자료

2-1-2. 기존 기능 수정 시 (fix) 항목

• 1. (사람이 작성하는 항목) 배경, 이슈 현상, 디버그
  • 1-*. (사람이 작성하는 항목) 현상/디버그, 참고 로직/원칙/세부사항
• 2. (사람이 작성하는 항목) 목표
  • 2-1. (사람이 작성하는 항목) 우선적으로 참조할 파일
• 3. (AI가 작성하는 항목) 이슈의 원인으로 의심되는 부분들
• 4. (AI가 작성하는 항목) 디버그 과정
• 5. (AI가 작성하는 항목) 파악한 이슈의 원인
• 6. (AI가 작성하는 항목) 생각한 수정 방안들 (최소 3가지)
• 6-*. (AI가 작성하는 항목) 처음에 생각한 코드 수정 방안
• 7. (AI가 작성하는 항목) 최종 결정된 수정 방안 (AI 가 자동 진행하면 안되고 무조건/MUST 사람에게 선택/결정을 맡겨야 한다)
  • 7-*. 최종 수정 방안을 결정한 구체적/명확한 이유 (단순한 이슈 안 됨)
• 8. (AI가 작성하는 항목) 코드 수정 요약
• 9. (AI가 작성하는 항목) 문제 해결에 참고한 자료

2-2. TODO Context-Free Key-Items 준수: 코드수정 진행상황에 따른 코드 수정 요약 checkbox 주의 사항

• 최종 수정 방안이 결정되고 나면, 코드 수정 요약에 checkbox 로 checklist 를 우선 만들어 놓고, 코드 수정이 진행되면 경과를 기록한다
  • context window 크기 제약 때문에 LLM 이 언제든지 이어서 할 수 있도록 구성

2-3. TODO Context-Free Key-Items 준수: Examples

todo-key-point-examples.md 참고

3. main stream agent 와 subagent 역할 분리

• main stream agent: 전체적인 지휘자, subagent: 실제 작업자
• 두 agent 모두 ### 5-2. 작업 시작 시: 모든 mark down 문서 find (공통사항) ~ #### 5-3-1. 최상단 README.md 에서 파악해야할 내용 (공통사항) 까지는 공통 사항으로 진행하여 이 프로젝트의 전체적인 맥락과 구성은 인지하고 있음
• main stream agent 는 전체적인 상세한 코드 내용은 모르지만, 이전 todo 작업들의 맥락과 현재 무슨 작업을 subagent 에게 할당하여 진행 중인지, 뭐가 문제인지 subagent 가 찾았다는 문제의 원인이 논리적으로 맞는지 판단하는 역할
• subagent 는 자기한테 할당된 현재 작업이 무엇인지, 상세하게 코드를 뒤져보는 역할

3-1. main stream agent 와 subagent 역할 분리: main stream agent 의 역할

main stream agent 는 전체적인 프로젝트 구조 파악 후 ### 2-1. TODO Context-Free Key-Items 준수: 핵심 작성 항목 의 항목 중, AI 가 작성하는 각 항목과 feat 의 ## 6. 코드 수정 요약, fix 의 ## 8. 코드 수정 요약 항목 하위의 세부사항을 별도의 context 를 가진 각 subagent 를 생성하여 지목하여 시키는 역할

3-2. main stream agent 와 subagent 역할 분리: subagent 의 역할

subagent 는 ### 2-1. TODO Context-Free Key-Items 준수: 핵심 작성 항목 의 항목 중, AI 가 작성하는 각 항목과 feat 의 ## 6. 코드 수정 요약, fix 의 ## 8. 코드 수정 요약 항목의 하위의 세부사항을 진행. 작업 중 의문이나 불명확한 사항이 생기면 Skill tool을 사용하여 question-guide skill 활성화하여 사용자에게 질문.

4. TODO Template 참고

4-1. TODO Template 참고: TODO 파일의 제목 format

todo 파일은 기본적으로 YYYY_MM_DD-issue<이슈번호>-<issue_name_only_english>.md 와 같은 format 으로 프로젝트의 docs 밑에 존재한다.

4-2. TODO Template 참고: main stream agent

• main stream agent 의 context 크기 관리를 위해, 필요한 경우 main stream agent 는 todo-template-fix.md, todo-template-feat.md 만 참고, todo-template-fix-2025_11_27-issue51-pancreas_percent_update_diagnosis.md, todo-template-feat-2025_12_24-issue33-front_file_upload.md 는 참고하지 않는다.

4-3. TODO Template 참고: subagent

• subagent 의 context 크기 관리를 위해, 필요한 경우 subagent 는 todo-template-fix-2025_11_27-issue51-pancreas_percent_update_diagnosis.md, todo-template-feat-2025_12_24-issue33-front_file_upload.md 예시도 추가로 참고 가능 (subagent 는 todo-template-fix.md, todo-template-feat.md 도 당연히 참고 가능)

---

5. 작업 시작 시

md 파일들과 git log, 코드 등을 확인하여 이전의 맥락을 파악한다

Script 사용 원칙: 모든 script는 --help 또는 -h 옵션으로 사용법 확인 가능

5-1. 작업 시작 시: 요금제 확인 및 모델 전략 결정 (main stream agent)

1. get-subscription-tier.sh 실행
2. model-strategy.md 참조
3. Free 요금제 → 사용자 경고 후 제한 작업

핵심: 분석=EnterPlanMode+opus, 수정=ExitPlanMode+sonnet, 단순실행=haiku

5-2. 작업 시작 시: 모든 mark down 문서 find (공통사항)

project 의 전반적인 구조와 아키텍쳐/구성요소 등을 알기 위해 전체 폴더에서 *.md 로 끝나는 파일들을 find

• find-markdown-files-all.sh [dir] 실행 (기본: 현재 경로)
• *.md 로 끝나는 모든 파일을 출력

5-2-1. Printed Examples (공통사항)

./ERD.md
./CHANGELOG.md
./CLUSTER_SETUP.md
./resources/migrations/postgres/README.md
./USER_APP_MANUAL.md
./docs/v04.03.00/781-feat-host-path-api.md
./docs/v04.03.00/795-extauthz-wildcard-cookie-backend.md
./docs/v04.03.00/credit-system.md
./docs/v04.03.00/766-binding-email.md
./docs/v04.03.00/686-frontend-mount.md
./docs/feature/resource/250421_Resource_Repository.md
./docs/feature/resource/250421_Resource_Service.md
./docs/feature/event/250422_RQueue.md
./README.md
./FUNCTION_FLOW.md
./DEPLOYMENT.md
./FILES.md
./FEATURE.md
./DEVELOPMENT.md
./front/README.md
./deployments/keycloak/README.md

5-3. 작업 시작 시: README.md 최상단 부터 읽기 (공통사항)

find-readme-files.sh [dir] 실행

• README.MD 라는 이름의 파일이 존재하는 폴더들을 확인하여 프로젝트 구성요소들을 파악
• 구성요소 마다 README.md 를 제대로 안 달아둔 프로젝트의 경우 제대로 구성요소가 파악이 안 될 수 있으니 필요한 경우 tree.sh [dir] [tree_options] 도 실행
• 그 후 최상단 README.md 부터 읽어가며 프로젝트를 파악한다

5-3-1. 최상단 README.md 에서 파악해야할 내용 (공통사항)

프로젝트 전체 개요 및 아키텍처 이해

• 프로젝트 목표와 핵심 변화
• 전체 아키텍처 다이어그램
• 컴포넌트 구성요소 및 하위 README 링크

5-3-2. 프로젝트 핵심 구조 파악 (공통사항)

• docker-compose.yml
• Dockerfile
• Makefile
• template.mk
• *.proto
• *_types.go
• schema.prisma
• schema.graphql
• shcema.sql
• Taskfile
• kustomization.yaml
• requirements.txt

5-4. 작업 시작 시: todos 최근 작업된 todo 파일들 list up (main stream agent)

find-recent-todos.sh [todo_dir] 실행하여 제목에 적힌 날짜 기준으로 최근 5 개 todo 파일을 list

5-4-1. todo 파일의 제목 format 이 다른 경우 (main stream agent)

YYYY_MM_DD-issue<이슈번호>-<issue_name_only_english>.md 와 같은 형태

• 위 ### 5-2. 작업 시작 시: 모든 mark down 문서 find (공통사항) 에서 확인했을 시 todo 문서 처럼 보이지만 제목 format 이 다른 파일이 있었을 경우, find-recent-todos-lt.sh [todo_dir] 를 실행하여 제목에 적힌 날짜 기준이 아닌 파일 수정 시간을 기준으로 최근 5개 todo 파일을 list
• 필요한 경우 find-recent-todos.sh 와 find-recent-todos-lt.sh 를 둘 다 실행한 후 결과를 비교하여, git log 로 어떤 이슈들이 작업되었는지 확인 필요

5-5. 작업 시작 시: todos 최근 변경 이력 및 진행 중인 작업 파악 (main stream agent)

위 ### 5-4. 작업 시작 시: todos 최근 작업된 todo 파일들 list up (main stream agent) 에서 실행하여 얻은 5개의 todo 파일에 대해 print-todo-core.sh <todo_file> 를 실행하여 각 todo 파일들의 fix 이면 ## 1. 현재 이슈 및 현상, 디버그 했던 내용, ## 2. 목표, ## 5. 파악한 이슈의 원인, ## 7. 최종 결정된 수정 방안, ## 8. 코드 수정 요약, feat 이면 ## 2. 요구사항, ## 3. 기존 코드/구현의 핵심내용들/의도들, ## 5. 최종 결정된 수정 방안, ## 6. 코드 수정 요약 을 상세 확인

• git log 로 최근 진행된 작업 확인, 실제 코드 확인은 subagent가 수행
• 현재 진행해야하는 todo.md 작업 특정
• 이슈 확인: Skill tool 을 사용하여 issue-fetcher skill 활성화해서, 현재 branch 가 issue 에 달려있는 MR/PR 중에 있는 branch 이름 중 하나랑 같은지 확인
  • 같지 않으면 사용자에게 branch 이름이 이슈에 있는 MR/PR 중에 없다고 만들어 달라고 알리고 더 이상 진행하지 않고 종료
• ### 4-2. TODO Template 참고: main stream agent 참고하여 template만 확인, 현재 진행해야하는 todo.md 안에서 ### 2-1. TODO Context-Free Key-Items 준수: 핵심 작성 항목 중 AI 가 작성하는 항목 중에서 어떤 항목을 실행할 차례인지 확정
• 별도 context의 subagent 생성하여 작업 지목
• 순차 실행 (병렬 금지), 하나 씩 결과 확인 후 순차 실행
• ## 6. 생각한 수정 방안들, ## 4. 생각한 수정 방안들 구현에 필요한 핵심 변경점 까지만 멈추지 말고 subagent 들로 실행하고, 꼭, 무조건, MUST ## 7. 최종 결정된 수정 방안, ## 5. 최종 결정된 수정 방안 진행 전에는 진행된 사항을 요약하여 사용자에게 설명하고 사용자에게 최종 방향을 결정을 물어 본 후에 진행한다.
• multi-agent-with-codex-gemini skill 은 각 작업이 종료 후, 수정 방안 고민/결정에 사용, 전체 코드를 훑어보고 codex 나 gemini 에게 의견을 물어보기 위해 사용, claude subagent 는 작업용

5-5-1. 작업 시작 시: subagent 에게 명시해야하는 항목 (main stream agent)

• Skill tool 을 사용하여 todo-management skill 활성화 명시
• 현재 작업 중인 todo.md 파일 경로
• 현재 작업 중인 ### 2-1. TODO Context-Free Key-Items 준수: 핵심 작성 항목
• git log/코드 탐색 지시
• 필요시 Skill tool 을 사용하여 추가 skill 활성화 명시 (question-guide, issue-fetcher, clean-code, design-pattern-advisor, git-bisect-auto, puppeteer-mcp, react-next-guide 등)
• 작업 완료 후 문서 업데이트 지시 (## 6. TODO 문서 update 시점 (subagent) 참고)

5-5-2. 작업 시작 시: '코드 수정 요약' 항목 주의사항 (main stream agent)

• ### 2-1. TODO Context-Free Key-Items 준수: 핵심 작성 항목 각각 subagent로 작업하되, ## 8. 코드 수정 요약, ## 6. 코드 수정 요약만 특별 처리
• 모델 배분: model-strategy.md 참조
  • checkbox 설계 -> opus subagent 1회 (### 2-2. TODO Context-Free Key-Items 준수: 코드수정 진행상황에 따른 코드 수정 요약 checkbox 주의 사항 참고), plan 등급 (Pro:sonnet, Max:opus)
  • 각 checkbox 실행 -> haiku subagent N회
  • 나머지 핵심 항목 -> sonnet subagent
• 순차 실행 필수 (병렬 금지), Task tool model parameter 사용

5-6. 작업 시작 시: 코드 상세 확인 (subagent)

• 프로젝트 구조, todo.md 파일, 할당된 작업을 파악 후 시작
• 특히 #### 5-3-2. 프로젝트 핵심 구조 파악 (공통사항) 에 언급된 내용들을 확인한다.
• 필요시 find-todo-by-issue-number.sh <issue_number> 나 find-todo-by-name.sh <name_pattern> 활용하여 사용자가 명시한 이슈나 todo 파일 확인
• 이슈 확인: Skill tool 을 사용하여 issue-fetcher skill 활성화
• 코드 변경 이력: Skill tool 을 사용하여 git-bisect-auto skill 활성화 또는 git log 로 확인
• 작업 중 의문/불명확한 사항 발생 시: Skill tool 을 사용하여 question-guide skill 활성화하여 사용자에게 질문
• main stream agent 가 명시한 skill 들과 추가로 할당 받은 작업에 필요한 skill Skill tool 을 사용하여 자율 활성화
• template 참고: ### 4-3. TODO Template 참고: subagent 참고 (template과 예시 모두)

---

6. TODO 문서 update 시점 (subagent)

• ### 2-1. TODO Context-Free Key-Items 준수: 핵심 작성 항목 에서 정의한 각 작업 완료 즉시 TODO 문서의 해당 섹션 update
• main stream agent 가 작업 할당 시 문서 update 까지 함께 지시 필요

6-1. TODO 문서 update 시점 (subagent): '코드 수정 요약' 항목의 checkbox

• #### 5-5-2. 작업 시작 시: '코드 수정 요약' 항목 주의사항 (main stream agent) 참고
• 작업 완료 시 checkbox 체크
• 마지막 checkbox 완료한 subagent 가 todo.md 파일명에 done_ prefix 추가

6-2. TODO 문서 update 시점 (subagent): 코드 내용 중복 방지 및 5W1H 준수

코드/config 파일이 git commit에 포함되는 경우, 파일 전체 내용을 md에 복사하지 않고 5W1H 원칙에 따라 설명만 작성:

설계 단계 (section 6, 7): 파일경로:위치 + What + How + Why

• 좋은 예: "back/api/percent.go의 calculateTotal() 함수: pathology를 totalSum 계산에서 분리하여 별도 변수로 계산 후 최종 합산. 이유: pathology는 다른 항목들과 가중치가 달라 별도 처리 필요"
• 나쁜 예: 함수 전체 코드 붙여넣기
• 나쁜 예: "back/api/percent.go 수정" (What, How 없음)

구현 단계 (section 8): 파일경로:라인 + What + How

• 좋은 예: "back/api/percent.go:45-60 pathology 계산 로직 분리: totalSum 계산에서 제외 → pathologySum 별도 변수로 계산 → 최종 return 시 합산"
• 나쁜 예: "back/api/percent.go 수정 완료" (What, How 없음)
• 나쁜 예: 수정된 전체 코드 붙여넣기

핵심 원칙:

• Where: 파일경로, 함수/클래스명, 라인 범위
• What: 무엇을 수정하는가
• How: 어떻게 수정하는가 (before → after 형태로)
• Why: 왜 이렇게 수정하는가 (설계 단계)
• 코드는 git diff로 확인 가능하므로 중복 금지