MH-DashBoard-organization/docs/WORK_RULEBOOK.md

Work Rulebook

Purpose

이 문서는 이 프로젝트에서 매일 작업을 시작하고 마무리할 때 반드시 따를 운영 규칙을 고정하기 위한 룰북이다.

목표는 아래 4가지다.

• 완료된 기능의 회귀 방지
• 코드 문제와 DB 문제의 혼선 방지
• 작업 기록 누락 방지
• 매일 같은 기준으로 안정적으로 이어서 작업

Rule 0. Morning Start Mandatory Check

이 규칙은 강제 규칙이다.

매일 아침 또는 그날의 첫 작업을 시작할 때는, 코드를 수정하기 전에 반드시 아래 순서를 먼저 수행한다.

1. Gitea 브랜치 상태 확인
2. 열린 이슈 확인
3. 이 문서 WORK_RULEBOOK.md 확인
4. 최신 체크포인트 문서 확인
5. 현재 워크트리의 미푸시 커밋, 변경 파일, 미추적 파일 확인

위 5단계를 확인하기 전에는 새 코드 작성, 기존 코드 수정, 임의 테스트 진행을 시작하지 않는다.

즉:

• "오늘 첫 작업"의 시작점은 코드 수정이 아니라 상태 확인이다.
• 이 절차를 건너뛰고 바로 수정 작업에 들어가는 것은 금지한다.

Rule 1. Completed Feature Protection

완료 판정된 작업물의 기능과 코드는 함부로 건드리지 않는다.

세부 규칙:

• 직접 관련된 이슈가 없으면 완료 기능을 수정하지 않는다.
• 완료 기능 수정이 필요하면 먼저 이유와 영향 범위를 이슈 또는 코멘트에 남긴다.
• 단순 편의상 구조를 바꾸거나 정리하는 리팩터링으로 완료 기능 동작을 바꾸지 않는다.
• 완료 기능을 수정한 경우에는 관련 회귀 검증까지 완료해야 한다.

핵심 원칙:

• "고치는 김에 같이 정리"를 금지한다.
• 수정 범위는 현재 작업 목적에 필요한 최소 범위로 제한한다.

Rule 2. Work Must Be Tied To An Issue

원칙적으로 이슈 없는 작업은 하지 않는다.

세부 규칙:

• 모든 작업은 기존 이슈에 연결하거나 새 이슈/작업 메모를 만든 뒤 시작한다.
• 왜 하는 작업인지 한 줄로라도 남긴다.
• 임시 대응도 예외가 아니다.

Rule 3. Branch And Workspace Awareness

작업 전에 현재 브랜치와 워크트리 상태를 먼저 확인한다.

반드시 확인할 항목:

• 현재 브랜치
• 원격 대비 ahead / behind 상태
• 미푸시 커밋
• 수정된 파일
• 미추적 파일

금지:

• 로컬에서만 있는 상태를 기준 진실처럼 가정하기
• 미정리 변경사항을 모른 채 새 작업을 덧붙이기

Rule 4. DB Before Code Assumption

조직도, 멤버, 자리배치도, 권한 문제는 코드보다 DB 상태 영향을 먼저 의심한다.

세부 규칙:

• dev DB와 prod DB가 다른데 코드 버그로 단정하지 않는다.
• 공개용 기준 데이터가 필요한 검증은 먼저 동기화 상태를 확인한다.
• DB 차이를 무시한 검증 결과를 신뢰하지 않는다.

Rule 5. Dev / Prod Protocol Is Mandatory

docs/DEV_PROD_DB_PROTOCOL.md 의 규칙은 권고가 아니라 작업 기준이다.

핵심 원칙:

• 코드 선행은 8081
• 데이터 정본은 8080
• 8081 DB는 독립 정본이 아니라 검증용 복제본처럼 다룬다

조직도/자리배치도/멤버 검증 전에는 필요 시 아래를 먼저 수행한다.

• ./scripts/sync_prod_db_to_dev.sh minimal

분석 화면까지 공개용 기준으로 맞출 필요가 있으면 아래를 사용한다.

• ./scripts/sync_prod_db_to_dev.sh full

Rule 6. Validation Before Completion

완료 기준은 "코드를 썼다"가 아니라 "실제 동작을 검증했다"이다.

세부 규칙:

• 검증 없이 완료로 판단하지 않는다.
• 감으로 확인하지 않고 체크리스트 기준으로 확인한다.
• 회귀 가능성이 있는 수정은 관련 기능까지 같이 확인한다.

검증 기준 문서:

• docs/REGRESSION_CHECKLIST.md

Rule 7. Seat Map Work Is High Risk

자리배치도 관련 작업은 항상 고위험 작업으로 취급한다.

작업 시 최소 확인 항목:

1. 관리자 DnD 배치 / 저장
2. 조직도 상세의 seat preview
3. 비관리자 seatmap 진입 / 표시

오피스가 여러 개면 아래 모두 확인한다.

• 기술개발센터
• 한맥빌딩 6층
• 한맥빌딩 7층

기술개발센터만 보고 완료 처리하지 않는다.

Rule 8. Auth / Schema / Sync Changes Are High Risk

아래 영역은 일반 기능 수정처럼 다루지 않는다.

• auth.*
• members
• seat_maps
• seat_slots
• seat_positions
• 동기화 스크립트
• 스키마 변경

이 작업은 반드시:

• 변경 이유 명시
• 영향 범위 확인
• 관련 검증 수행
• 결과 기록

까지 포함해야 한다.

Rule 9. Temporary Logic Must Be Tracked

mock, fallback, hotfix, 임시 우회 로직은 허용할 수 있다. 하지만 반드시 추적 가능해야 한다.

세부 규칙:

• 왜 임시인지 기록한다.
• 제거 또는 정식화할 이슈를 연결한다.
• 운영 기준 로직처럼 장기 방치하지 않는다.

Rule 10. End-Of-Day Closing Record

작업 종료 시 아래를 반드시 남긴다.

• 무엇을 했는지
• 무엇을 검증했는지
• 무엇이 아직 남았는지
• 다음에 어디서 이어야 하는지

남길 위치:

• Gitea 이슈 코멘트
• 또는 체크포인트 문서

둘 다 가능하면 둘 다 남긴다.

Rule 11. Commit And Push Need Explicit User Instruction

커밋과 푸시는 자동으로 하지 않는다.

세부 규칙:

• 코드 수정, 문서 수정, 검증 작업은 커밋 없이 계속 진행할 수 있다.
• git commit 은 사용자가 명시적으로 지시한 경우에만 수행한다.
• git push 도 사용자가 명시적으로 지시한 경우에만 수행한다.
• 작업 중간 상태는 워크트리에 남겨둘 수 있으며, 임의로 잘라서 자주 커밋하지 않는다.
• 커밋이 필요하다고 판단되면 먼저 상태와 이유를 공유하고, 지시를 받은 뒤 진행한다.

Rule 12. Promote 8081 To 8080 By Reviewed File Diff Only

8081 작업용에서 검증된 변경을 8080 공개용으로 가져갈 때는 전체 workspace 를 통째로 덮지 않는다.

세부 규칙:

• 먼저 8081 작업용의 변경 파일 목록과 diff 를 확인한다.
• 공개용에 필요한 파일만 선택해서 메인 workspace 로 반영한다.
• 반영 후에는 메인 workspace 기준으로 최소 회귀 검증을 다시 수행한다.
• 8081 DB 기준으로만 맞는 수정인지, 8080 기준 데이터에서도 맞는지 다시 확인한다.
• 검증이 끝나기 전에는 공개용 완료로 판단하지 않는다.

금지:

• 8081 작업 디렉터리를 통째로 복사해서 8080에 덮어쓰기
• diff 확인 없이 일괄 반영
• 8081에서 됐으니 8080도 같을 것이라고 가정하기

Rule 13. 8081 Must Start From The Isolated Worktree

8081 작업용은 포트만 다른 복제 서버가 아니라, 코드 소스까지 분리된 전용 worktree여야 한다.

세부 규칙:

• 8081은 항상 /tmp/mh-dashboard-organization-dev-worktree에서 띄운다.
• 기동 전 ./scripts/prepare_dev_worktree.sh를 먼저 실행한다.
• .env와 로컬 전용 디자인 자산은 준비 스크립트가 복사한 것을 기준으로 사용한다.
• 기동 후 docker inspect mh-dashboard-organization-dev-backend-1로 마운트 소스를 확인한다.

금지:

• 현재 메인 workspace를 직접 마운트한 상태로 8081을 띄우기
• 8080과 8081이 같은 frontend/public, legacy/static, incoming-files를 동시에 보게 두기
• 8081에서 보이던 디자인을 8080 공통 소스에 바로 덮어쓰기

Daily Start Checklist

매일 첫 작업 시작 전 체크:

• 현재 브랜치 확인
• 원격 대비 커밋 상태 확인
• 열린 이슈 확인
• WORK_RULEBOOK.md 확인
• 최신 체크포인트 확인
• 미추적 / 수정 파일 확인
• 현재 작업은 커밋 없이 진행하고, 커밋/푸시는 지시받을 때만 한다는 규칙 확인
• 오늘 작업이 코드 문제인지 DB 문제인지 먼저 구분
• 공개용 기준 데이터 검증이 필요한지 판단

Daily End Checklist

매일 작업 종료 전 체크:

• 오늘 변경 파일 정리
• 검증 결과 정리
• 미완료 항목 정리
• 관련 이슈 코멘트 또는 문서 업데이트
• 다음 시작 지점 명시

One-Line Operating Principle

이 프로젝트의 작업 기준은 아래 한 줄로 요약한다.

• 상태를 먼저 확인하고, 완료 기능은 보호하며, DB와 검증을 무시하지 않고, 기록을 남기면서 작업한다.