MH-DashBoard-organization/docs/WORK_EXECUTION_FLOW.md

Work Execution Flow

목적

이 문서는 앞으로 이 프로젝트에서 작업을 어떤 순서로 진행해야 하는지 아주 쉽게 고정하기 위한 문서다.

세미나에서 들은 흐름을 이 프로젝트 기준으로 다시 쓰면 아래 순서다.

1. SSOT 먼저 확인
2. 이슈 생성 또는 연결
3. 완료조건 먼저 적기
4. 실행 계획 적기
5. 필요한 동기화 먼저 하기
6. 코드 수정 / 화면 작업 수행
7. 가드레일 테스트
8. 기록 남기기

이 순서를 지키는 이유는 하나다.

• 작업 도중 기준이 바뀌지 않게 하기
• 임시 연결이 누적되지 않게 하기
• 나중에 봐도 왜 이렇게 했는지 알 수 있게 하기
• 8081 작업이 8080을 망가뜨리지 않게 하기

1. SSOT 먼저 확인

SSOT는 Single Source Of Truth 의 줄임말이다.

쉬운 말로:

• "무엇을 기준 진실로 볼 것인가"

이걸 먼저 정하지 않으면 작업 중간에 기준이 계속 바뀌어서 코드가 꼬인다.

이 프로젝트에서 자주 쓰는 SSOT:

• 공개용 코드 기준: /home/hyunho/projects/mh-dashboard-organization
• 작업용 코드 기준: /home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081
• 데이터 정본 기준: 8080 DB
• 기능 검증 기준: 8081
• 사업관리대장 디자인 기준: MH 통합 대시보드_260320.html
• 허브 공통 시각 언어 기준: sample style.css
• 현재 작업 지시 기준: 연결된 Gitea 이슈

작업 시작 전에 먼저 정해야 하는 질문:

• 이번 작업의 코드 기준은 어디인가?
• 이번 작업의 데이터 기준은 어디인가?
• 이번 화면의 디자인 기준 파일은 무엇인가?
• 지금 바꾸려는 화면이 실제로 어떤 파일에서 렌더링되는가?

이걸 모르고 코드를 건드리면 높은 확률로 엉뚱한 파일을 수정하게 된다.

2. 이슈 생성 또는 연결

작업은 이슈 없이 하지 않는다.

이유:

• 왜 하는 작업인지 남기기 위해
• 중간에 범위가 커지는 걸 막기 위해
• 다음 세션에서 바로 이어가기 위해

좋은 이슈는 아래 4개가 있어야 한다.

1. 배경
2. 목표
3. 현재 상태
4. 남은 작업

이슈는 길게 쓸 필요는 없다. 하지만 최소한 아래는 있어야 한다.

• 왜 이 작업을 하는지
• 어디까지가 이번 범위인지
• 무엇을 완료로 볼지

3. 완료조건 먼저 적기

이 단계가 중요하다.

완료조건이 없으면 "대충 된 것 같음" 상태에서 끝나기 쉽다.

좋은 완료조건 예시:

• 8081이 .dev-worktree-8081를 실제로 마운트한다
• 사업관리대장 탭이 원본 기준 레이아웃으로 열린다
• 8080은 영향 없이 유지된다
• 관련 회귀 검증을 통과한다

나쁜 완료조건 예시:

• 화면이 좀 괜찮아 보인다
• 아마 될 것 같다
• 코드 정리함

완료조건은 반드시 확인 가능한 문장이어야 한다.

즉:

• "봤을 때 예쁨"이 아니라
• "어떤 URL에서 어떤 동작이 확인됨"이어야 한다

4. 실행 계획 적기

계획은 길 필요 없다.

이 프로젝트에서는 보통 아래 정도면 충분하다.

1. 기준 파일과 현재 연결 구조 확인
2. 8081 worktree 기준으로만 수정
3. 필요한 데이터 동기화
4. 화면/기능 수정
5. 회귀 검증
6. 이슈 코멘트와 체크포인트 기록

핵심은:

• 수정 전에 먼저 구조를 파악하고
• 범위를 정하고
• 검증까지 포함해서 끝내는 것

5. 실행 전 동기화

이 프로젝트는 코드만 맞아도 안 되고, 데이터도 맞아야 한다.

그래서 실행 전에 동기화가 필요할 수 있다.

무슨 뜻이냐면:

• 8081에서 기능 확인을 하더라도
• 데이터가 8080과 다르면 검증 결과를 신뢰하면 안 된다

자주 쓰는 규칙:

• 조직도 / 멤버 / 자리배치 검증 전
  • ./scripts/sync_prod_db_to_dev.sh minimal
• 분석 화면까지 공개용 기준으로 맞춰야 할 때
  • ./scripts/sync_prod_db_to_dev.sh full

또 코드 동기화도 중요하다.

• 8081은 메인 workspace에서 직접 띄우지 않는다
• 먼저 ./scripts/prepare_dev_worktree.sh
• 그 다음 .dev-worktree-8081에서 실행

즉 이 프로젝트의 동기화는 두 종류다.

• DB 동기화
• 코드/worktree 동기화

6. 실제 실행

이 단계가 코드를 고치는 단계다.

하지만 여기서도 규칙이 있다.

• 8081에서 먼저 작업
• 기준 파일이 아닌 곳은 건드리지 않기
• 임시 우회 연결을 만들었으면 반드시 기록 남기기
• 연결 구조가 난잡해지면 바로 이슈에 코드 정리 필요를 남기기

특히 이 프로젝트는 아래가 자주 꼬인다.

• frontend/public
• legacy/static
• incoming-files
• 정적 HTML
• iframe 연결
• 버전 쿼리스트링

그래서 실행 중 계속 확인해야 한다.

• 지금 내가 고친 파일이 실제 서빙 파일이 맞는가?
• 지금 수정이 8081 전용인가, 8080 공통인가?
• 이 연결은 임시인가, 기준 구조인가?

7. 가드레일 테스트

가드레일 테스트는 쉬운 말로:

• "이 수정 때문에 같이 망가지면 안 되는 것들을 확인하는 테스트"

즉 핵심 기능만 보는 게 아니라, 같이 깨지기 쉬운 주변 기능까지 확인하는 것이다.

이 프로젝트에서 가드레일 테스트 예시:

• 8081 디자인 수정 후
  • 8080은 그대로인지 확인
• 조직현황 수정 후
  • 조직도 iframe, 모달, 리스트뷰, seat preview 확인
• 자리배치 수정 후
  • 관리자 저장
  • 비관리자 조회
  • 조직도 상세 seat preview
• 분석 화면 수정 후
  • 기간 필터
  • 프로젝트/팀 전환
  • 빈 데이터 상태
  • 스타일 깨짐 여부

가드레일 테스트는 "다 테스트한다"가 아니다.

이번 수정 때문에 같이 깨질 가능성이 높은 것만 빠르게 확인하는 것이다.

8. 기록 남기기

작업은 기록까지 남겨야 끝난다.

남겨야 하는 것:

• 무엇을 바꿨는지
• 무엇을 기준으로 했는지
• 무엇을 검증했는지
• 무엇이 아직 안 끝났는지
• 다음에 어디서 이어야 하는지

남길 위치:

• Gitea 이슈 코멘트
• 체크포인트 문서
• 필요하면 룰북/프로토콜 문서

이 프로젝트용 한 줄 버전

앞으로는 아래 순서로 생각하면 된다.

1. 기준 진실부터 정한다
2. 이슈에 작업 목적과 완료조건을 적는다
3. 실행 전에 코드/DB 동기화를 맞춘다
4. 8081에서만 수정한다
5. 같이 깨지면 안 되는 것까지 확인한다
6. 결과를 기록한다

시작할 때 바로 쓰는 짧은 템플릿

작업 시작 전에 아래 6줄만 적어도 된다.

• SSOT:
  • 코드 기준:
  • 데이터 기준:
  • 디자인 기준:
• 이슈:
• 완료조건:
• 계획:
• 필요한 동기화:
• 가드레일 테스트:

예시:

• SSOT:
  • 코드 기준: /home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081
  • 데이터 기준: 8080 DB를 sync한 8081
  • 디자인 기준: MH 통합 대시보드_260320.html
• 이슈: #16
• 완료조건: 8081에서 사업관리대장 메인이 원본 톤으로 열리고 8080은 안 바뀜
• 계획: 연결 확인 → worktree 수정 → 검증 → 이슈 기록
• 필요한 동기화: minimal
• 가드레일 테스트: 8080 유지, 조직현황 탭, 프로젝트/팀 탭