sodalive-backend-spring-boot/docs/plan-task/20260513_에이전트문서작업절차개선.md

에이전트 문서 작업 절차 개선 계획

구현 계획

Phase 1: 기존 문서 확인

• Task 1.1: 기존 에이전트 문서 확인
  • 파일 경로: AGENTS.md, docs/agent-guides/작업절차.md, docs/agent-guides/문서유지보수.md, docs/prd/sample-prd.md
  • 검증 기준: 현재 규칙, 샘플 PRD 위치, 기존 사용자 변경 여부를 확인한다.
• Task 1.2: 기존 PRD와 계획 문서 재사용 여부 확인
  • 파일 경로: docs/prd/20260513_에이전트문서작업절차개선_prd.md, docs/plan-task/20260513_에이전트문서작업절차개선.md
  • 검증 기준: 같은 작업의 후속 수정이므로 새 문서를 만들지 않고 기존 문서에 누적한다.

Phase 2: 문서 규칙 갱신

• Task 2.1: PRD 문서에 후속 요구사항 누적
  • 파일 경로: docs/prd/20260513_에이전트문서작업절차개선_prd.md
  • 검증 기준: 새 폴더 구조, phase/task 형식, task별 검증 기록과 전체 검증 기록 구분, 가이드 분리 요구사항이 포함된다.
• Task 2.2: AGENTS.md 핵심 링크 갱신
  • 파일 경로: AGENTS.md
  • 검증 기준: 실행 명령어와 커밋 메시지 상세 규칙을 직접 중복하지 않고 별도 agent-guides 문서를 참조한다.
• Task 2.3: 작업 절차 가이드 갱신
  • 파일 경로: docs/agent-guides/작업절차.md
  • 검증 기준: PRD 작성, 사용자 인터뷰, 계획/TASK 작성 후 구현, 범위 변경 시 계획 선갱신 절차가 포함된다.
• Task 2.4: 문서 유지보수 가이드 갱신
  • 파일 경로: docs/agent-guides/문서유지보수.md
  • 검증 기준: docs/[날짜]_구현할내용한글/prd.md, docs/[날짜]_구현할내용한글/plan-task.md, phase/task 형식, task별 검증 기록과 전체 검증 기록 구분 규칙이 포함된다.
• Task 2.5: 실행 명령어 가이드 분리
  • 파일 경로: docs/agent-guides/실행명령어.md
  • 검증 기준: Gradle 실행 명령어가 별도 문서에 정리된다.
• Task 2.6: 커밋 메시지 가이드 분리
  • 파일 경로: docs/agent-guides/커밋메시지.md
  • 검증 기준: 커밋 형식과 검증 절차가 별도 문서에 정리된다.
• Task 2.7: 검증 기록 위치 규칙 보강
  • 파일 경로: docs/prd/20260513_에이전트문서작업절차개선_prd.md, docs/agent-guides/작업절차.md, docs/agent-guides/문서유지보수.md, docs/plan-task/20260513_에이전트문서작업절차개선.md
  • 검증 기준: 개별 task 검증 기록은 해당 task 아래에 남기고, 여러 task/phase 또는 전체에 해당하는 검증 기록은 문서 하단에 남긴다는 규칙이 포함된다.
  • 검증 기록:
    • 무엇을: PRD와 agent guide의 검증 기록 위치 규칙을 task별 기록과 전체 기록으로 분리했다.
    • 왜: 검증 결과를 구현 단위 가까이에 두고, 하단 검증 기록은 전체 회귀와 교차 phase 검증 용도로 유지하기 위해서다.
    • 어떻게: rg -n "문서 하단|해당 task 아래|전체에 해당|검증 기록|검증 결과" docs/agent-guides/작업절차.md docs/agent-guides/문서유지보수.md docs/prd/20260513_에이전트문서작업절차개선_prd.md docs/plan-task/20260513_에이전트문서작업절차개선.md로 반영 문구를 확인했다.

Phase 3: 검증

• Task 3.1: 문서 변경 내용 확인
  • 파일 경로: AGENTS.md, docs/agent-guides/*.md, docs/prd/20260513_에이전트문서작업절차개선_prd.md, docs/plan-task/20260513_에이전트문서작업절차개선.md
  • 실행 명령: git diff -- AGENTS.md docs/agent-guides docs/prd/20260513_에이전트문서작업절차개선_prd.md docs/plan-task/20260513_에이전트문서작업절차개선.md
  • 기대 결과: 요청 범위의 문서 변경만 포함된다.
• Task 3.2: Gradle 명령 유효성 확인
  • 파일 경로: build.gradle.kts, settings.gradle.kts
  • 실행 명령: ./gradlew tasks --all
  • 기대 결과: Gradle task 목록 조회가 성공한다.
• Task 3.3: 검증 기록 위치 규칙 문서 변경 범위 확인
  • 파일 경로: docs/agent-guides/작업절차.md, docs/agent-guides/문서유지보수.md, docs/prd/20260513_에이전트문서작업절차개선_prd.md, docs/plan-task/20260513_에이전트문서작업절차개선.md
  • 실행 명령: git diff -- docs/agent-guides/작업절차.md docs/agent-guides/문서유지보수.md docs/prd/20260513_에이전트문서작업절차개선_prd.md docs/plan-task/20260513_에이전트문서작업절차개선.md
  • 기대 결과: 검증 기록 위치 규칙 관련 문서 변경만 포함된다.
  • 검증 기록:
    • 무엇을: 이번 후속 문서 변경의 diff 범위를 확인했다.
    • 왜: 요청한 검증 기록 위치 규칙 외의 문서나 코드가 함께 변경되지 않았는지 확인하기 위해서다.
    • 어떻게: git diff -- docs/agent-guides/작업절차.md docs/agent-guides/문서유지보수.md docs/prd/20260513_에이전트문서작업절차개선_prd.md docs/plan-task/20260513_에이전트문서작업절차개선.md로 변경 범위를 확인했다.

검증 기록

• 1차 PRD/계획 작성
  • 무엇을: 사용자 요청에 따라 구현 전 PRD와 계획 TASK 문서를 먼저 작성했다.
  • 왜: 새 규칙 자체가 PRD와 계획 TASK 문서 없이 구현하지 않는 흐름을 요구하므로, 이번 문서 변경에도 동일한 절차를 적용하기 위해서다.
  • 어떻게: docs/prd/sample-prd.md에서 필요한 섹션을 발췌해 docs/prd/20260513_에이전트문서작업절차개선_prd.md를 작성하고, 구현 체크리스트를 docs/plan-task/20260513_에이전트문서작업절차개선.md에 정리했다.
• 2차 문서 반영 및 검증
  • 무엇을: AGENTS.md, docs/agent-guides/작업절차.md, docs/agent-guides/문서유지보수.md에 PRD와 계획 TASK 문서 작성 순서, 저장 위치, 파일명 규칙, 사용자 인터뷰 규칙을 반영했다.
  • 왜: 에이전트가 구현 전에 요구사항을 PRD로 고정하고, 모호한 사항을 사용자 인터뷰로 해소한 뒤 계획 TASK 문서를 기준으로 최소 구현하도록 문서 간 규칙을 일치시키기 위해서다.
  • 어떻게: 변경한 Markdown 문서 5개에 대해 lsp_diagnostics를 실행해 모두 No diagnostics found를 확인했고, ./gradlew tasks --all 실행 결과 BUILD SUCCESSFUL in 13s를 확인했다.
• 3차 후속 규칙 수정 및 검증
  • 무엇을: 문서 저장 규칙을 docs/[날짜]_구현할내용한글/prd.md, docs/[날짜]_구현할내용한글/plan-task.md 형식으로 변경하고, 계획/TASK phase 형식과 검증 기록 누적 규칙을 보강했다. 실행 명령어와 커밋 메시지 규칙은 각각 docs/agent-guides/실행명령어.md, docs/agent-guides/커밋메시지.md로 분리했다.
  • 왜: 사용자 요청에 따라 구현 전 PRD/계획 문서 준비 절차를 더 명확히 하고, AGENTS.md의 상세 규칙 중복을 줄이기 위해서다.
  • 어떻게: git diff -- AGENTS.md docs/agent-guides docs/prd/20260513_에이전트문서작업절차개선_prd.md docs/plan-task/20260513_에이전트문서작업절차개선.md로 요청 범위의 문서 변경을 확인했다. ./gradlew tasks --all은 샌드박스에서 ~/.gradle lock 파일 접근 권한 문제로 1차 실패했고, 권한 승격 후 재실행해 BUILD SUCCESSFUL in 20s를 확인했다.
• 4차 검증 기록 위치 규칙 수정 및 검증
  • 무엇을: 개별 task 검증 기록은 해당 task 아래에 남기고, 여러 task/phase 또는 전체에 해당하는 검증 기록은 하단 검증 기록에 누적하도록 PRD와 agent guide를 갱신했다.
  • 왜: 검증 결과를 구현 단위 가까이에 두어 추적성을 높이고, 하단 검증 기록은 전체 회귀와 교차 phase 검증 용도로 유지하기 위해서다.
  • 어떻게: rg -n "문서 하단|해당 task 아래|전체에 해당|검증 기록|검증 결과" docs/agent-guides/작업절차.md docs/agent-guides/문서유지보수.md docs/prd/20260513_에이전트문서작업절차개선_prd.md docs/plan-task/20260513_에이전트문서작업절차개선.md와 git diff -- docs/agent-guides/작업절차.md docs/agent-guides/문서유지보수.md docs/prd/20260513_에이전트문서작업절차개선_prd.md docs/plan-task/20260513_에이전트문서작업절차개선.md로 반영 내용과 변경 범위를 확인했다.