sodalive-android/docs/20260601_계획문서규칙수정/plan-task.md

20260601 계획 문서 규칙 수정

개요

• 작업 절차와 PRD/계획/TASK 문서 작성 규칙을 사용자 요청 기준으로 수정한다.
• PRD: docs/20260601_계획문서규칙수정/prd.md

구현 범위

• Create: docs/20260601_계획문서규칙수정/prd.md
• Create: docs/20260601_계획문서규칙수정/plan-task.md
• Modify: AGENTS.md
• Modify: docs/agent-guides/work-plan-docs.md

작업 체크리스트

Phase 1: 작업 문서 준비

• Task 1.1: PRD 문서 작성
  • 파일 경로: docs/20260601_계획문서규칙수정/prd.md, docs/prd/sample-prd.md
  • 검증 기준: sample-prd.md의 필요한 섹션만 사용하고, 이번 작업의 목표/범위/제약을 명시한다.
• Task 1.2: 계획/TASK 문서 작성
  • 파일 경로: docs/20260601_계획문서규칙수정/plan-task.md
  • 검증 기준: phase heading, 체크박스 task, 파일 경로, 검증 기준을 포함한다.

Phase 2: 규칙 문서 수정

• Task 2.1: AGENTS.md 작업 절차 핵심 규칙 수정
  • 파일 경로: AGENTS.md
  • 실행 명령: sed -n '1,220p' AGENTS.md
  • 기대 결과: 작업 시작 전 PRD와 계획/TASK 문서 준비, 새 문서 경로, 인터뷰/연속 작업/검증 기록 누적 규칙이 반영된다.
• Task 2.2: work-plan-docs.md 작업 계획 문서 규칙 수정
  • 파일 경로: docs/agent-guides/work-plan-docs.md
  • 실행 명령: sed -n '1,260p' docs/agent-guides/work-plan-docs.md
  • 기대 결과: 사용자 요청의 문서 구조, 작성 순서, sample PRD, phase/task, 범위 변경, 검증 기록 규칙이 반영된다.
• Task 2.3: 신규 문서에만 새 규칙 적용 명시
  • 파일 경로: AGENTS.md, docs/agent-guides/work-plan-docs.md, docs/20260601_계획문서규칙수정/prd.md
  • 검증 기준: 기존에 생성된 docs/prd/, docs/plan-task/ 문서는 유지하고, 신규 생성 문서부터 새 docs/[날짜]_구현할내용한글/ 구조를 적용한다고 명시한다.

Phase 3: 검증 및 기록

• Task 3.1: 변경 범위와 규칙 문구 검증
  • 파일 경로: AGENTS.md, docs/agent-guides/work-plan-docs.md, docs/20260601_계획문서규칙수정/prd.md, docs/20260601_계획문서규칙수정/plan-task.md
  • 실행 명령: rg -n "docs/\\[날짜\\]_구현할내용한글|docs/prd/|docs/plan-task/|sample-prd|Phase 1|검증 기록" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정
  • 기대 결과: 새 규칙은 반영되고, canonical 안내에서 기존 docs/prd/, docs/plan-task/ 생성 규칙은 제거된다.
• Task 3.2: 검증 기록 누적
  • 파일 경로: docs/20260601_계획문서규칙수정/plan-task.md
  • 검증 기준: 문서 하단에 무엇/왜/어떻게, 실행 명령, 결과를 한국어로 누적 기록한다.

2026-07-30 후속 실행 정보

문서 항목	내용
상태	구현 완료
요구사항 기준	docs/20260601_계획문서규칙수정/prd.md의 12. 2026-07-30 후속 변경
샘플 기준	docs/sample/sample-plan-task.md
현재 Phase	Phase 4: 샘플 문서와 리뷰 보고서 규칙
현재 활성 Goal	없음(별도 goal 생성 요청 없음)

목표

PRD·구현 계획/TASK·리뷰 보고서의 기준 샘플과 유지보수 절차를 명확히 하고, 리뷰에서 확정된 수정 항목을 해당 Phase의 신규 Task로 바로 전환할 수 있게 한다.

범위

포함

• AGENTS.md의 작업 절차 핵심 규칙
• docs/agent-guides/work-plan-docs.md의 상세 작성·유지보수·리뷰 후속 규칙
• 기존 PRD와 계획/TASK 문서의 후속 요구사항·Task·검증 기록 누적

제외

• 과거 작업 문서의 일괄 변환
• Android 앱 소스와 빌드 설정 변경
• 일반 빌드·테스트·린트 결과를 위한 리뷰 보고서 생성
• 실제 코드 리뷰를 수행하지 않는 이번 문서 정비 작업의 reviews/ 폴더 생성

기술적 제약

• Markdown 문서만 수정한다.
• 사용자 작업인 docs/prd/sample-prd.md 삭제와 docs/sample/의 신규 샘플 3종을 변경하지 않는다.
• 기존 완료 Task와 검증 기록을 삭제하거나 미완료로 되돌리지 않는다.
• 제공되지 않은 리뷰 파일 이름이나 범위는 미리 만들지 않는다.
• 문서 Task는 production 동작을 변경하지 않아 TDD를 적용하지 않고 경로·문구 대조와 명령 검증으로 대체한다.

Phase 4: 샘플 문서와 리뷰 보고서 규칙

Phase 결과: 에이전트가 세 샘플의 정확한 위치를 따라 문서를 작성하고, 코드 리뷰 결과와 확정 수정 항목을 일관된 경로와 Task로 추적할 수 있다.

선행조건: Phase 3 완료와 DEC-001~003 확정.

Phase 완료 조건: P4-T1~P4-T3, P4-T5, P4-GATE, P4-GATE-2의 체크리스트와 완료 증거가 모두 충족되고 검증 기록이 누적된다.

Task 4.1 후속 요구사항과 실행 계획 확정

Goal 실행 P4-T1: 새 샘플과 사용자 결정을 기존 PRD·계획/TASK 문서에 추적 가능한 후속 범위로 기록한다.

• 시작 조건: docs/sample/의 샘플 3종과 사용자 결정 확인.

• 완료 증거: PRD의 DOC-001~004, REV-001~005, DEC-001~003과 이 Phase의 Task·완료 조건.

• 범위 밖: 규칙 문서와 샘플 원문 수정.

• TDD 예외 사유: production 동작을 변경하지 않는 문서 계획 Task다.

• 대체 검증 방법: 샘플 경로, 요구사항 ID, Task 연결을 rg와 git diff --check로 대조한다.

• docs/sample/sample-prd.md, docs/sample/sample-plan-task.md, docs/sample/sample-review.md의 구조와 경로를 확인한다.

• 사용자 결정과 리뷰 후속 절차를 prd.md에 누적한다.

• 기존 완료 Task를 유지하고 Phase 4 실행 계획을 추가한다.

Task 4.2 AGENTS.md 핵심 규칙 갱신

Goal 실행 P4-T2: 작업 시작 시 샘플 위치와 리뷰 보고서·후속 수정의 필수 순서를 바로 확인할 수 있게 한다.

• 시작 조건: P4-T1 완료.
• 완료 증거: DOC-001~004, REV-001~005의 핵심 원칙이 AGENTS.md에 요약되고 상세 가이드 경로가 유지된다.
• 범위 밖: 상세 템플릿 전체 복제와 다른 실행 원칙 수정.
• TDD 예외 사유: 에이전트 안내 문구만 변경하는 문서 Task다.
• 대체 검증 방법: 세 샘플 경로, reviews/ 경로, 해당 Phase 신규 Task 선행 규칙을 검색해 확인한다.

Files:

• Modify: AGENTS.md

• 기존 sample-prd.md 안내를 docs/sample/sample-prd.md의 정확한 경로로 바꾼다.

• 구현 계획/TASK 문서가 docs/sample/sample-plan-task.md를 참조하도록 명시한다.

• 리뷰 보고서 대상·샘플·저장 경로와 일반 검증 제외 규칙을 요약한다.

• 확정 리뷰 항목은 코드 수정 전에 해당 Phase의 신규 회귀 수정 Task로 추가하도록 명시한다.

• 기존 완료·검증·리뷰 기록 보존 규칙을 유지한다.

검증 기록(2026-07-30):

• rg -n "docs/sample/sample-(prd|plan-task|review)\\.md|reviews/|신규 회귀 수정 Task|기존 완료 Task|빌드.*테스트.*린트|샘플.*변경" AGENTS.md 실행 결과, 세 샘플 경로와 리뷰 보고서·후속 Task·기록 보존 규칙을 확인했다.
• git diff --check -- AGENTS.md는 출력 없이 exit code 0으로 통과했다.

Task 4.3 work-plan-docs.md 상세 규칙 갱신

Goal 실행 P4-T3: 문서 작성, 샘플 동기화, 리뷰 보고서 작성, 확정 항목의 수정 전환 절차를 하나의 상세 가이드에서 확인할 수 있게 한다.

• 시작 조건: P4-T2 완료.
• 완료 증거: PRD·계획/TASK·리뷰 보고서별 샘플과 작성 절차, 문서 유지보수 규칙, 리뷰 후속 Task 전환 규칙이 구체적으로 기록된다.
• 범위 밖: 샘플 문서 원문 변경과 코드 리뷰 수행.
• TDD 예외 사유: 작업 절차 문구만 변경하는 문서 Task다.
• 대체 검증 방법: 요구사항별 문구 대조표와 경로 검색, Markdown diff 검증을 사용한다.

Files:

• Modify: docs/agent-guides/work-plan-docs.md

• PRD와 계획/TASK 문서의 기준 샘플 경로와 placeholder 구체화 규칙을 명시한다.

• 리뷰 보고서 생성 대상, sample-review.md, reviews/[리뷰범위]-review.md 경로를 명시한다.

• 일반 빌드·테스트·린트 결과는 Task별 검증 기록 또는 Verification Log에 남기도록 구분한다.

• 확정 리뷰 항목을 review ID와 연결한 해당 Phase 신규 회귀 수정 Task로 먼저 추가하고 바로 수정하는 순서를 명시한다.

• 샘플 위치·구조·작성 규칙 변경 시 AGENTS.md와 관련 가이드를 함께 동기화하도록 유지보수 규칙을 추가한다.

검증 기록(2026-07-30):

• rg -n "docs/sample/sample-(prd|plan-task|review)\\.md|reviews/|신규 회귀 수정 Task|기존 완료 Task|빌드.*테스트.*린트|샘플.*변경" docs/agent-guides/work-plan-docs.md 실행 결과, 기준 샘플·리뷰 보고서·확정 항목 전환·유지보수 규칙을 확인했다.
• rg -n '### Phase [0-9]|docs/prd/sample-prd\\.md|체크박스.*Task N\\.N' AGENTS.md docs/agent-guides/work-plan-docs.md는 결과가 없어 폐기된 경로와 이전 Phase/Task 형식 안내가 남지 않았음을 확인했다.
• git diff --check -- docs/agent-guides/work-plan-docs.md는 출력 없이 exit code 0으로 통과했다.

Phase 4 Gate

Goal 실행 P4-GATE: 샘플 경로, 리뷰 보고서 범위, 확정 항목 전환 순서, 기존 기록 보존 규칙의 문서 간 정합성을 판정한다.

• 시작 조건: P4-T1~P4-T3 완료.

• 완료 증거: 아래 명령이 성공하고 실제 결과가 검증 기록에 누적된다.

• 범위 밖: 앱 빌드·테스트와 과거 문서 일괄 정비.

• Task 4.4: 문서 정합성 및 명령 유효성 검증

rg -n "docs/sample/sample-(prd|plan-task|review)\\.md|reviews/|신규 회귀 수정 Task|빌드.*테스트.*린트" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정
git diff --check
./gradlew tasks --all

Expected: 세 샘플의 정확한 경로와 리뷰 후속 절차가 문서 간 일치하고, whitespace 오류가 없으며 Gradle task 목록 조회가 exit code 0으로 끝난다.

검증 기록(2026-07-30):

• 문서 검색은 세 샘플 경로, 리뷰 보고서 대상, 일반 검증 제외, 확정 항목의 신규 회귀 수정 Task 전환 규칙을 모두 찾고 exit code 0으로 끝났다.
• git diff --check는 출력 없이 exit code 0으로 통과했다.
• 최초 ./gradlew tasks --all은 sandbox가 ~/.gradle lock 파일 접근을 차단해 실패했다. 같은 명령을 승인된 권한 범위에서 재실행해 BUILD SUCCESSFUL in 24s, 1 actionable task: 1 executed를 확인했다.

Task 4.5 리뷰 범위 파일명 형식 추가

Goal 실행 P4-T5: 리뷰 보고서명만으로 대상 Phase와 구현 내용을 식별할 수 있게 [리뷰범위] 형식을 고정한다.

• 시작 조건: DEC-004, REV-006 확정.
• 완료 증거: AGENTS.md와 work-plan-docs.md에 phase<번호>-<구현 내용을 나타내는 영문 kebab-case> 형식과 실제 파일명 예시가 일치하게 기록된다.
• 범위 밖: 기존 리뷰 보고서 파일의 일괄 이름 변경과 샘플 문서 원문 수정.
• TDD 예외 사유: 파일명 작성 규칙만 변경하는 문서 Task다.
• 대체 검증 방법: 형식·예시 검색, 전체 diff whitespace 검사, Gradle task 목록 조회로 검증한다.

Files:

• Modify: AGENTS.md

• Modify: docs/agent-guides/work-plan-docs.md

• Modify: docs/20260601_계획문서규칙수정/prd.md

• Modify: docs/20260601_계획문서규칙수정/plan-task.md

• PRD에 REV-006, DEC-004, 파일명 수용 기준을 추가한다.

• AGENTS.md에 [리뷰범위] 형식과 예시를 추가한다.

• work-plan-docs.md에 [리뷰범위] 구성 요소와 예시를 추가한다.

• 문서 간 형식·예시가 일치하는지 검증한다.

검증 기록(2026-07-30):

• 형식·예시 검색으로 네 문서가 같은 신규 규칙을 안내함을 확인했다.
• AGENTS.md, work-plan-docs.md, prd.md를 대상으로 phase-2-review.md를 검색한 결과가 없어 실제 규칙에는 이전 예시가 남지 않았음을 확인했다. plan-task.md에는 검증에 사용한 검색어가 과거 실행 기록으로만 남아 있다.
• git diff HEAD --check는 출력 없이 exit code 0으로 통과했다.

Phase 4 재검증 Gate

Goal 실행 P4-GATE-2: 후속 파일명 규칙이 기존 리뷰 보고서 경로·후속 수정 절차와 충돌하지 않는지 판정한다.

• 시작 조건: P4-T5 완료.

• 완료 증거: 아래 명령이 성공하고 실제 결과가 검증 기록에 누적된다.

• 범위 밖: 기존 리뷰 보고서 파일 이름 변경.

• Task 4.6: 리뷰 보고서명 규칙 재검증

rg -n "phase<번호>-<구현 내용을 나타내는 영문 kebab-case>|phase2-main-home-recommendation-review\\.md" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정
git diff HEAD --check
./gradlew tasks --all

Expected: 네 문서가 같은 [리뷰범위] 형식과 예시를 안내하고, whitespace 오류가 없으며 Gradle task 목록 조회가 exit code 0으로 끝난다.

검증 기록(2026-07-30):

• 형식·예시 검색은 네 문서에서 phase<번호>-<구현 내용을 나타내는 영문 kebab-case>와 phase2-main-home-recommendation-review.md를 확인하고 exit code 0으로 끝났다.
• git diff HEAD --check는 출력 없이 exit code 0으로 통과했다.
• ./gradlew tasks --all은 BUILD SUCCESSFUL in 4s, 1 actionable task: 1 executed로 통과했다.

검증 기록

• 2026-06-01

  • 무엇/왜/어떻게: 계획 문서 규칙 수정 요청에 따라 기존 작업 절차 문서와 sample-prd.md 위치를 확인하고, 신규 작업 문서부터 docs/[날짜]_구현할내용한글/prd.md, docs/[날짜]_구현할내용한글/plan-task.md 구조를 적용하도록 규칙을 수정했다.
  • 실행 명령:
    • rg --files -g 'AGENTS.md' -g 'sample-prd.md' -g 'docs/**'
    • sed -n '1,240p' AGENTS.md
    • sed -n '1,260p' docs/agent-guides/work-plan-docs.md
    • sed -n '1,240p' docs/prd/sample-prd.md
  • 결과:
    • sample-prd.md가 docs/prd/sample-prd.md에 있음을 확인했다.
    • 기존 규칙이 docs/prd/, docs/plan-task/ 분리 저장을 안내하고 있음을 확인했다.
    • 새 PRD/계획 문서는 docs/20260601_계획문서규칙수정/ 아래에 생성했다.

• 2026-06-01

  • 무엇/왜/어떻게: 사용자가 기존에 생성된 문서는 두고 신규 생성 문서만 새 규칙을 적용하면 된다고 정정해, 해당 범위 조건을 PRD와 규칙 문서에 추가로 명시했다.
  • 실행 명령:
    • rg -n "docs/\\[날짜\\]_구현할내용한글|docs/prd/|docs/plan-task/|sample-prd|Phase 1|검증 기록|신규 생성 문서|기존에 생성된" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정
    • git diff -- AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정/prd.md docs/20260601_계획문서규칙수정/plan-task.md
    • git status --short
  • 결과:
    • AGENTS.md와 docs/agent-guides/work-plan-docs.md에 신규 문서 경로와 기존 문서 유지 조건이 반영됐음을 확인했다.
    • 변경 범위가 AGENTS.md, docs/agent-guides/work-plan-docs.md, docs/20260601_계획문서규칙수정/prd.md, docs/20260601_계획문서규칙수정/plan-task.md로 제한됐음을 확인했다.

• 2026-07-30

  • 무엇/왜/어떻게: 새 PRD·계획/TASK·리뷰 보고서 샘플과 코드 리뷰 후속 수정 절차를 작업 규칙에 반영했다. 기존 작업의 연속 범위이므로 새 작업 폴더를 만들지 않고 Phase 4와 후속 요구사항을 기존 문서에 누적했다.
  • 실행 명령:
    • rg -n "docs/sample/sample-(prd|plan-task|review)\\.md|reviews/|신규 회귀 수정 Task|빌드.*테스트.*린트" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정
    • git diff --check
    • ./gradlew tasks --all
  • 결과:
    • AGENTS.md와 docs/agent-guides/work-plan-docs.md에서 세 샘플의 정확한 경로, 리뷰 보고서 저장 위치, 일반 검증 제외, 확정 항목의 해당 Phase 신규 Task 전환 규칙을 확인했다.
    • git diff --check는 출력 없이 exit code 0으로 통과했다.
    • ./gradlew tasks --all은 최초 sandbox 권한 제한을 확인한 뒤 승인 범위에서 재실행해 BUILD SUCCESSFUL in 24s로 통과했다.
    • 이번 작업은 코드 리뷰를 수행하지 않은 문서 정비이므로 reviews/ 폴더와 리뷰 보고서를 생성하지 않았다.

• 2026-07-30

  • 무엇/왜/어떻게: 사용자 후속 요청에 따라 리뷰 보고서명의 [리뷰범위]를 phase<번호>-<구현 내용을 나타내는 영문 kebab-case>로 고정하고, phase2-main-home-recommendation-review.md 예시를 핵심·상세 규칙과 PRD에 일치하게 반영했다.
  • 실행 명령:
    • rg -n "phase<번호>-<구현 내용을 나타내는 영문 kebab-case>|phase2-main-home-recommendation-review\\.md" AGENTS.md docs/agent-guides/work-plan-docs.md docs/20260601_계획문서규칙수정
    • git diff HEAD --check
    • ./gradlew tasks --all
  • 결과:
    • 네 문서가 같은 [리뷰범위] 형식과 실제 파일명 예시를 안내함을 확인했다.
    • git diff HEAD --check는 출력 없이 exit code 0으로 통과했다.
    • ./gradlew tasks --all은 BUILD SUCCESSFUL in 4s로 통과했다.