L09 — wiki 변경 거버넌스: 공유 문서를 누가 어떻게 바꾸나 (수정중)

1. 무엇을 푸는 문제인가 — 공유 문서의 두 축

팀 wiki(/home/ubuntu/wiki, GitHub popupstudio-ai/wiki)는 여러 사람이 같이 만지는 공유 문서다. 포트 표, 서버 구성, 온보딩 절차, 트러블슈팅… 운영 지식이 다 여기 모인다.

여럿이 같이 만지는 순간 두 가지 질문이 생긴다.

• 접근 권한 — 누가 직접 쓸 수 있나? 전원? 아니면 관리자만?
• 변경 관리 — 누군가 바꾼 걸 어떻게 검토·통제하나? 막을까, 사후에 볼까?

"wiki 변경 거버넌스"는 이 두 축에 대한 팀의 약속이다. 거버넌스란 어려운 말 같지만, "공유 문서를 누가 어떻게 바꾸나"를 정해둔 규칙이라는 뜻이다. 이번 강의는 그 약속이 어떻게 결정됐는지(실제 세션) 와 무엇으로 확정됐는지(wiki-governance.md) 를 같이 본다. 소스는 2026-06-20 세션 session_01QbW9XeVaxpZoFBE2G4UZSb 와 그 결과 문서 wiki/infrastructure/wiki-governance.md 다.

2. 출발점 — "공유 리소스는 잠가야 하지 않나?"

세션은 단순한 질문에서 시작했다 — "gun, eunseo 같은 devteam 유저가 ubuntu 홈의 프로젝트에 쓰기 권한이 있나?"

확인해 보니 공유 리소스 중 standarda-core · standarda-template · standarda(venv) · shared-docs 는 devteam 직접 쓰기를 막고(🔒 read-only, 즉 읽기만 되고 못 고침 — 바꾸려면 PR 또는 ubuntu 경유), wiki 만 쓰기를 유지하기로 1차 정리됐다.

그러자 자연스러운 후속 직관이 나왔다.

"wiki 도 포트 표나 프로젝트 생성·삭제에 필요한 파일 말고는, devteam 이 못 쓰게(ubuntu 만 관리) 하는 게 맞지 않나?"

직관적으로는 "관리 문서니까 잠그자"가 맞아 보인다. 여기서부터가 이 강의의 핵심 — 그 직관을 그대로 따르지 않고, 잠금의 실익을 따져본 과정이다.

3. 왜 "차단"이 아니라 "사후 검토"인가 — 잠금의 실익을 따지다

"wiki 를 read-only 로 잠그자"에 대해, 잠금이 실제로 무엇을 얻는지 하나씩 짚었다. 잠금의 목적은 보통 "아무나 못 바꾸게 + 누가 바꿨는지 통제"인데, 그게 이미 다른 방식으로 충족되고 있었다.

• 이미 git history 로 누가 바꿨는지 되짚을 수 있다. wiki 의 모든 변경은 커밋으로 남고, 팀원이 각자 고유 git 신원으로 찍는다(gun·eunseo·hyeonjin… 서로 다른 author). → git log/git blame 으로 "누가·언제·무엇을"이 전부 추적된다. 잠가서 추가로 얻는 통제가 거의 없다.
• 막아도 우회된다. devteam 은 풀 NOPASSWD sudo(비밀번호 없이 관리자 권한을 쓸 수 있음, 2026-06-20~)라, read-only 여도 sudo 로 그냥 편집할 수 있다. 즉 read-only 는 진짜 차단이 아니라 "실수 방지 속도방지턱" 수준이다. (게다가 sudo 사용도 auth.log 에 남아 추적된다.)
• 글로벌 정책과 충돌한다. 글로벌 CLAUDE.md 에 "운영 지식·절차가 생기면 wiki 에 문서화할 것"이 있다. 이건 devteam 의 직접 쓰기를 전제한 정책이다. 잠그면 "문서화하려면 매번 sudo·ubuntu 경유"가 돼 정책과 어긋난다.

여기에 git 특유의 함정이 하나 더 있었다. 한 repo 안에서 "이 파일만 쓰기 가능"은 잘 안 된다. 포트 표만 고쳐도 commit 하려면 .git/ 에 써야 한다. 게다가 git pull 은 바뀐 아무 추적 파일이나 덮어쓰는데, 그 파일이 read-only 면 pull 자체가 깨진다.

정리하면 선택지는 셋이었다.

권고는 A(이미 history+sudo 로 추적되고 정책과도 합치). 통제가 정말 필요하면 C 말고 B. 사용자는 A(현행 유지) 를 택했다 — 단, "ubuntu 외 유저가 wiki 를 수정했을 때 이를 관리할 정책은 필요하다" 는 조건을 달았다. 차단은 안 하되, 가시성은 확보하자는 것이다.

핵심 교훈: "공유물은 잠근다"는 기본값을 의심하라. 이미 git history·sudo 로그로 추적되는 신뢰 팀에서는, 차단보다 "직접 쓰기 + 사후 알림"이 비용 대비 효과가 낫다.

4. 결정의 반전 — "현재 실제 상태"를 확인하자 방향이 갈렸다

"사후 검토 정책"을 GitHub Action(push 시 검토 이슈 자동 생성)으로 구현하던 중, 실제 GitHub 권한을 확인하자 전제가 뒤집혔다.

• on-box(/home/ubuntu/wiki)는 devteam 그룹 쓰기였지만, GitHub wiki repo 는 devteam 전원이 read 전용이었다(admin 인 chris·chongyochon 만 push). 최근 wiki 커밋 16건이 전부 chris 인 것과 일치.
• 즉 devteam 은 wiki 의 canonical(팀 전체가 공유하는 진짜 원본) GitHub 버전을 애초에 못 바꾸고 있었다. 그러니 push 를 기준으로 도는 검토 Action 은 devteam 에겐 발동조차 안 된다(그들이 push 를 못 하므로).

그래서 다시 두 갈래로 좁혀졌다.

• A. 현행 GitHub 권한 유지 (admin 만 push) — devteam 은 on-box 로컬만 편집, GitHub 동기화·검토는 chris.
• B. devteam(fde_dev 팀)에 wiki push 권한 부여 — 직접 commit·push 가능해지고, 그래야 사후 검토 Action 이 의도대로 작동.

사용자는 B 를 택했다. 통제를 푸는 방향이지만, "직접 문서화"라는 팀 문화에 맞춘 선택이다. → fde_dev 팀에 wiki write 부여(gun read→write 확인), 그 위에 사후 검토 알림을 얹는 것으로 최종 확정.

핵심 교훈: 정책은 머릿속 모델이 아니라 "현재 실제 상태"를 먼저 확인하고 설계한다. "devteam 은 wiki 에 쓸 수 있다"고 가정하고 push-기반 Action 을 만들었지만, 실제로는 GitHub read-only였다 — 확인 안 했으면 동작하지 않는 정책을 만들 뻔했다. (강의노트 작성 규칙 RULE-005 와 같은 정신: 인프라·권한은 추정 말고 실제 설정으로 검증)

5. 확정된 정책 — wiki-governance.md

세션의 결론은 wiki/infrastructure/wiki-governance.md(2026-06-20 확정)로 문서화됐다. 핵심만 추리면:

기본 정책 — 직접 쓰기 허용 + 사후 검토 (비차단) - devteam 멤버는 wiki 를 직접 편집·commit·push 할 수 있다(read-only 로 잠그지 않음). - 대신 ubuntu(chris-popup) 외 계정이 '관리 문서'를 바꾸면 자동으로 검토 이슈가 생성되어 Chris 가 사후 검토한다. 차단하지 않으므로 일상 마찰이 없다.

접근 권한 (B 결정) - GitHub wiki repo: fde_dev 팀에 push(write) 부여 → devteam 전원 직접 push 가능. - on-box /home/ubuntu/wiki: devteam 그룹 쓰기(2775) 유지. - safe.directory: 공유 repo 소유자가 ubuntu 라, devteam 이 그 안에서 git 작업 시 "dubious ownership" 오류가 난다 → /etc/gitconfig(system)에 safe.directory=/home/ubuntu/wiki 등록(개인 셋업은 scripts/setup_devtools_env.sh). - ⚠️ 공유 wiki 작업트리에서 sudo git ... 금지 (§6 참조).

자동 알림 Action — .github/workflows/wiki-change-review.yml - 트리거: master push - 대상: github.actor != chris-popup (= ubuntu 외 계정) - 제외 파일: infrastructure/server-environment.md (포트 레지스트리 — 워크플로우가 일상적으로 수정하므로 알림 안 함) - 동작: 제외 파일 외 변경이 있으면 변경 파일·커밋·diff 링크를 담은 검토 이슈 생성 + chris-popup 멘션·assign(wiki-review 라벨)

즉 포트 표만 바뀌면 조용하고, 그 외 관리 문서가 비-ubuntu 계정으로 바뀔 때만 Chris 에게 알림이 간다.

devteam 멤버가 관리 문서 편집 → commit(본인 신원) → push
  → Action 감지 (actor ≠ chris-popup, 포트표 외 변경)
  → '📝 wiki 검토' 이슈 자동 생성 + Chris 멘션/assign
  → Chris 가 diff 확인 → 정상이면 close / 문제면 revert·수정 후 close

이 흐름은 세션에서 처음부터 끝까지(end-to-end) 실제로 돌려 확인했다 — gun 이 일반 문서를 push 하니 검토 이슈 #3 이 자동 생성됐고(@chris-popup 멘션), gun 이 포트 표만 push 했을 땐 Action 은 돌되 이슈는 안 생겼다(조용).

6. 운영 중 실제로 터진 함정 — "공유 wiki 에서 sudo git 금지"의 유래

정책을 구현·테스트하는 과정에서 두 가지 git 함정이 실제로 터졌다. 정책 문서의 ⚠️ 규칙은 책상이 아니라 이 사고에서 나왔다.

• dubious ownership(수상한 소유권 경고) — gun 이 공유 /home/ubuntu/wiki(소유자 ubuntu)에서 commit 하려 하자 git 안전장치가 막았다. → system gitconfig 에 safe.directory 등록으로 해결(§5).
• sudo git reset --hard 사고 — 테스트 잔여물을 정리하려고 sudo git reset --hard 를 썼더니, ① server-environment.md 가 root 소유·644(그룹 쓰기 없음) 로 바뀌어 devteam 쓰기가 막혔고(→ ubuntu:devteam 664 로 복구), ② 그 시점 누군가 커밋 안 해둔 포트 표 변경분이 reset 으로 사라졌다(unstaged, 즉 아직 git 에 담아두지 않은 상태라 복구 불가 → 정직하게 공개·사과).

여기서 나온 규칙이 정책 문서의 경고다.

⚠️ 공유 wiki 작업트리에서 sudo git ... 금지 — sudo git reset/checkout 등은 파일을 root 소유로 바꾸고 타인의 미커밋 변경을 날릴 수 있다. 항상 본인 신분으로 git 을 쓴다.

교훈: 거버넌스는 정책 문장만으로 완성되지 않는다. 실제로 돌려보며 터지는 함정(권한 꼬임·소유권·미커밋 유실)을 규칙으로 환류시켜야 다음 사람이 같은 사고를 안 친다.

오늘 정리 + 다음

• 정리: wiki 거버넌스는 접근 권한(누가 쓰나)과 변경 관리(어떻게 검토하나) 두 축의 약속이다. 결론은 "직접 쓰기 허용 + 사후 검토(비차단)" — fde_dev 팀에 push 권한을 주되, ubuntu 외 계정이 포트 표 외 문서를 바꾸면 GitHub Action 이 검토 이슈를 자동 생성해 Chris 가 사후에 본다. 차단(PR 강제) 이 아니라 알림 을 고른 이유는 ① 이미 git history·sudo 로그로 추적되고 ② 글로벌 "wiki 에 문서화" 정책과 합치하며 ③ git 마찰이 없기 때문이다.
• 흔한 함정: 공유 wiki 작업트리에서 sudo git 을 쓰는 것. 파일이 root 소유로 바뀌고 남이 커밋 안 한 변경이 날아간다. 항상 본인 신분으로 git 을 쓴다.
• 다음 시간: 같은 M5 의 다른 조직 학습 주제(코드 리뷰 흐름, 교훈 전파 시스템)로 이어간다. 검토 Action 내부(wiki-change-review.yml)를 직접 뜯어보고 싶으면 자습으로.
• 자습 권장: 팀 wiki 의 infrastructure/wiki-governance.md(정책 원문), infrastructure/home-directory-permissions.md·infrastructure/sudo-policy.md(권한·sudo 배경)를 읽어 본다. 그리고 "우리 팀의 다른 공유 리소스(예: 공유 스크립트)는 어떤 거버넌스가 맞을지" 같은 축(접근권한·변경관리)으로 따져 본다.