MMX Beta Project Documents 계획, 근거, 댓글이 같은 기록으로 남는 작업 저장소
BETA_DOC_POLICY_001

BETA_DOC_POLICY_001

베타 문서 작성 및 관리 규정 · 2026-05-22 · Active · CODEX PM

1. 문서 루트

베타 문서 포털 루트는 www/public/project_document 이다.

2. 폴더 구조

  • reports: Task 단위 계획, 업무지시, 결과보고.
  • issues: blocker, 리스크, 기술 미확정, 재작업 사유.
  • decisions: owner 결정, PM 판정, 운영 규정, scope와 기술 방향 결정.
  • releases: 배포 이력, revision, 이미지 digest, 배포 시각 기록.

3. Reports 규칙

  1. Task는 reports/{Task-ID}_{Task-Name}/ 폴더 단위로 관리한다.
  2. 각 Task 폴더에는 개요와 진행 내역을 담은 index.html을 둔다.
  3. 각 Task 폴더는 implementation_plan.md, work_instruction.md, implementation_result_report.md를 기본 문서로 가진다.
  4. 본문 문서의 원본 형식은 기본적으로 md로 한다.
  5. 동일 내용을 가진 md와 html을 독립 원본으로 함께 운영하지 않는다.
  6. html은 카테고리 index, Task index, 또는 게시용 파생 문서에 한정한다.

4. Index 규칙

  1. root index는 중요 문서 바로가기와 신규 등록 문서 최근 10개를 표시한다.
  2. 신규 등록 문서 최근 10개의 시각 표시는 문서 생성시각이 아니라 최종 수정시각 기준으로 한다.
  3. 동일 문서의 .md와 .html이 함께 존재하더라도 신규 등록 문서 최근 10개에는 중복 노출하지 않는다.
  4. 각 카테고리 index는 문서 생성, 변경, 삭제 시 함께 갱신한다.
  5. Task index는 목표, 상태, 진행 내역, 문서 링크, 검증 상태를 보여준다.
  6. 배포 후에는 releases/index.html에 해당 배포 이력을 먼저 추가한 뒤 보고한다.
  7. Release 항목에는 최소한 service, revision, deployedAtKst, image, task를 기록한다.

5. 댓글 규칙

  1. 댓글 UI는 문서 footer에서 공통 제공한다.
  2. 댓글이 필요한 문서는 /project_document/view/... 경로로 연다.
  3. 기본 입력은 닉네임과 의견 본문이다.
  4. 작성, 편집, 삭제 동작 시 공유 편집 비밀번호를 묻고 API 환경변수 PROJECT_DOCUMENT_EDIT_PASSWORD로 검증한다.

6. 문서 버전 규칙

  1. 구현계획서는 팀이 일정 기간 기준으로 삼을 수 있도록 넓은 범위와 검증 기준을 먼저 적는다.
  2. 작은 보정, 질문, 누락 확인, 실행 중 판단 근거는 문서 댓글로 남긴다.
  3. 범위, 목표, 아키텍처 방향, 완료 판정이 달라지는 큰 변경만 새 문서 버전으로 올린다.
  4. 새 버전 문서를 만들면 Task index와 root recent list에서 현재 기준 문서를 분명히 표시한다.

7. 공개 경계

public 아래 문서는 웹 게시 대상이다. secret, 토큰, 개인정보, 시나리오 truth 원문, 비공개 계약정보는 올리지 않는다.

8. 책임

CODEX PM은 문서 구조, index 갱신, 댓글 일관성을 관리한다. CODEX PM은 root recent list의 시각, 중복 노출, 대표 문서 선택 기준이 정책과 일치하도록 유지한다. CODEX PM은 배포 완료 후 Release 섹션에 revision, 서비스, 시각, digest, 작업 설명(task)을 기록한 뒤 보고한다. 완료 판정은 검증 증거를 기준으로 한다.

부록 A. 문서 작성 및 등록 FAQ

  1. 문서는 md와 html 중 무엇을 원본으로 써야 하나?
    본문 문서는 md를 원본으로 쓴다. html은 index 또는 게시용 파생 문서에 한정한다.
  2. 같은 문서를 md와 html 둘 다 recent list에 올려도 되나?
    안 된다. 같은 문서는 대표 1건만 recent list에 노출한다.
  3. recent list 시각은 생성시각인가 수정시각인가?
    최종 수정시각 기준이다.
  4. 문서를 만들었는데 Root Recent Documents에만 보이고 Reports, Issues, Decisions에는 안 보일 수 있나?
    그럴 수 있다. recent list는 자동 반영되지만 각 카테고리 index와 release 기록은 별도 갱신이 필요할 수 있다.
  5. 완료라고 보고하려면 어디까지 끝나야 하나?
    이 대화 기준에서 완료는 배포와 검증까지 끝난 상태를 뜻한다. 작성 완료, 커밋 완료, 배포 완료, 검증 완료를 구분해 보고한다.
  6. Release 기록은 언제 갱신하나?
    배포 후 보고 전에 먼저 갱신한다. Root recent release와 MMX Beta Releases에서 확인 가능해야 한다.
  7. 링크가 열리지 않으면 무엇을 먼저 의심해야 하나?
    view 경로 안의 문서 index는 상대경로보다 절대경로가 안전하다. 특히 하위 문서 링크는 /project_document/view/... 절대경로 우선으로 점검한다.
  8. 새 Task 문서를 만들면 어떤 세트를 기본으로 갖춰야 하나?
    최소한 task index, implementation plan, work instruction이 필요하다. 상황에 따라 issues, decisions, subtask 문서를 같이 둔다.
  9. 세부 문서는 언제 subtask로 분리하나?
    구현, 서버, UI, 플랫폼 이식처럼 작업 경계가 분명하고 향후 독립 승격 가능성이 있으면 처음부터 subtask 문서로 분리한다.
  10. 문서 작업에 너무 힘을 빼지 않으려면 어떻게 해야 하나?
    상위 task 문서와 핵심 issue/decision, 필요한 subtask까지만 먼저 작성한다. 이후엔 구현에 들어가고, 문서는 구현 판단과 검증 결과가 생길 때만 보강한다.

댓글