#협업
20개의 포스트
![[특집] '홈페이지 개선'은 왜 3주째 진행 중일까 — 이슈를 어떤 단위로, 어떻게 적을 것인가](/_next/image?url=https%3A%2F%2Ffiles.core.today%2Fstorage%2Fcoredot%2Fpublic%2Fblog%2Fiss-cover.webp&w=3840&q=75)
[특집] '홈페이지 개선'은 왜 3주째 진행 중일까 — 이슈를 어떤 단위로, 어떻게 적을 것인가
업무 보드에 '홈페이지 개선'이라는 카드가 3주째 진행 중입니다. 담당자는 매일 일했는데 카드는 끝나지 않습니다. 끝난 모습이 적혀 있지 않기 때문입니다. 이 글은 일을 '얼마나 잘게 나눌까'보다 '무엇을 하나의 완료로 볼 것인가'를 먼저 묻습니다. 팀이 추적하는 결과, 내가 시작하는 첫 행동, 일하며 남기는 기록, 나중에 다시 쓰는 지식은 서로 다른 단위입니다. 빌 웨이크의 INVEST와 마이크 콘의 SPIDR, Shape Up의 '어피타이트', 사이먼 윌리슨이 이슈를 실험 노트처럼 쓰는 법, 코치 토니의 '첫 행동', 칼 뉴포트의 조사 업무 준비, 예정일과 마감일의 분리, 제텔카스텐의 원자성과 '수집가의 오류', 그리고 AI 에이전트에게 일을 맡기는 2026년의 이슈까지. 원문을 하나씩 확인한 출처 서른한 건과 인터랙티브 4개, 삽화 12장으로 정리했습니다.
팀 프로젝트 폴더 구조 — 단일 파일에서 도메인형까지 (FastAPI 입문 7편)
한 파일짜리 할 일 API를 여러 사람이 동시에 고쳐도 충돌하지 않는 구조로 옮긴다. 단일 파일·계층형·도메인형 세 가지 폴더 구조를 비교하고 고르는 기준을 세운 뒤, 권장하는 도메인형 구조를 사용자·할 일 두 도메인으로 실제로 만들어 테스트까지 통과시킨다. 라우터는 얇게, 규칙은 service에, 저장은 repository에 두는 법, 도메인 사이 import 규칙, APIRouter·Depends·dependency_overrides, pyproject.toml·uv.lock·.env.example 같은 루트 파일, 팀 규칙과 PR 체크리스트까지 — FastAPI 입문 시리즈의 마지막 편이다. 댓글 기능 하나를 추가할 때 구조마다 무엇을 건드리는지 보여 주는 폴더 탐험기 위젯을 포함한다.
/docs 하나로 협업하기 — Swagger UI·ReDoc·OpenAPI 제대로 쓰는 법 (FastAPI 입문 3편)
FastAPI가 자동으로 만들어 주는 /docs(Swagger UI), /redoc, /openapi.json 세 주소를 실제 화면 캡처와 함께 설명한다. Try it out으로 요청을 보내고 응답을 읽는 법, tags·summary·description·examples·responses·deprecated로 문서 품질을 끌어올리는 법, openapi.json으로 프론트엔드 타입을 자동 생성하는 법, 운영 환경에서 문서를 닫는 법까지. 체험판 Swagger UI 위젯으로 할 일 API를 직접 호출해 볼 수 있다.
쿠버네티스 첫걸음 6편 — 네임스페이스와 Git으로 팀과 협업하기: context 규칙, Kustomize, 권한까지
혼자 쓰던 쿠버네티스를 팀과 함께 쓰면 새 문제가 생깁니다. 동료의 파드를 지우고, 운영 클러스터에서 실습 명령을 치고, 누가 무엇을 바꿨는지 아무도 모릅니다. 네임스페이스로 공간을 나누고, context 이름 규칙과 프롬프트 표시로 실수를 막고, 매니페스트를 Git에 두고 kubectl diff·apply만으로 바꾸는 원칙, Kustomize로 개발·운영의 차이를 한 저장소에서 다루는 법, 기본 제공 view 역할로 동료에게 읽기 권한만 주는 RBAC까지 실습합니다. 도커 compose.yaml 각 줄이 쿠버네티스에서 무엇이 되는지 보여 주는 대응 위젯과 팀 README 템플릿으로 시리즈를 마무리합니다.
도커 첫걸음 5편 — Docker Compose로 팀과 협업하기: compose.yaml 하나로 온보딩을 한 줄로
실제 앱은 API 서버, 데이터베이스, 캐시가 함께 돕니다. docker run을 세 번, 긴 옵션과 함께 치는 대신 compose.yaml 파일 하나에 적고 docker compose up 한 줄로 띄웁니다. 컨테이너끼리는 localhost가 아니라 서비스 이름으로 통신한다는 핵심 개념, DB가 준비될 때까지 기다리는 healthcheck, 비밀번호를 .env로 분리하는 법, 코드를 고치면 바로 반영되는 개발 모드를 익힙니다. 이어서 이미지를 GitHub Container Registry로 공유하는 흐름, GitHub Actions로 맥·서버 겸용 이미지를 자동 빌드하는 워크플로, 저장소에 무엇을 커밋할지 정하는 팀 규칙과 README 템플릿까지 — 시리즈를 협업으로 마무리합니다.
Git, 이것만 알면 협업한다 8편 — 한 걸음 더: rebase·cherry-pick·과거 커밋 둘러보기
시리즈 보너스 편입니다. 6편에서 개념만 짚은 rebase를 실제로 써 보고(충돌 풀기, pull --rebase, --force-with-lease, rebase -i로 커밋 정리, reflog로 되돌리기), 다른 브랜치의 커밋 하나만 가져오는 cherry-pick, 그리고 과거 커밋을 열어 보고 파일을 되살리는 법과 detached HEAD 경고의 뜻까지 git 2.55 실제 출력으로 따라갑니다.
같은 달을 보며 지붕을 하나씩 밟는다 — 조정량을 줄이는 법과 정원사의 리더십 (조정의 역풍 5편·완결)
네 편에 걸쳐 역풍이 어디서 오는지 봤다. 마지막 편은 저자의 해법이다. 점균류와 싸우지 말고 그 강점에 기댄다. 불필요한 조정을 놓아 두고, 결합을 풀고, 역풍을 계산에 넣어 아이디어를 다시 고른다. 그리고 3~5년의 달을 함께 정한 뒤, 달로 직진하는 대신 지붕까지의 안전한 도약을 반복한다. 여러 팀이 같은 달을 보면 각자 움직여도 수렴한다. 아이디어 비교기와 roofshot 계획기로 두 원칙을 직접 만져 보고, 건축가가 아니라 정원사로 조직을 보는 마지막 비유로 시리즈를 마무리한다.
모두 바쁜데 왜 아무것도 완성되지 않는가 — 빙산 아래의 비용과 여섯 가지 잘못된 처방 (조정의 역풍 4편)
참여 확률과 조직 역풍, 두 부품이 합쳐진 조정의 역풍은 불확실성이 크고 팀이 크고 문화가 상향식일수록 허리케인이 된다. 그것을 감당하는 데 드는 시간은 실제로 들어가지만 아무도 계산하지 않는다. 빙산의 끝만 보인다. 그래서 모두가 예전처럼 일정을 잡고, 예전처럼 일하고, 몇 배의 노력을 잡아먹는 프로젝트 앞에서 번아웃 직전이 된다. Komoroske가 그린 '영웅적 분투 → 변경 → 불확실성 → 더 큰 역풍'의 악순환과, 그것을 고치려다 오히려 악화시키는 여섯 가지 처방을 빙산 계산기와 판단 퀴즈로 짚는다.
사람은 로봇이 아니다 — 관계 마찰과 조직도 거리가 만드는 두 번째 역풍 (조정의 역풍 3편)
지금까지 성공 확률은 '팀이 제때 노력을 투입할 확률'만으로 계산했다. 사람을 확률을 가진 부품처럼 다룬 것이다. Komoroske는 85장에서 이 가정을 깬다. 두 사람이 함께 일하면 마찰점이 생길 수 있고, 열 명이면 관계는 45쌍이다. 그리고 두 사람이 조직도에서 멀수록 그 마찰을 풀어 줄 중재자가 멀어져, 문제는 올라가지 않고 곪는다. 관계 수 탐색기와 조직도 에스컬레이션 시뮬레이터로 '조직 역풍'이 왜 가장 작은 팀을 요구하는지 확인한다.
스프레드시트 몇 칸 채우는 일이 왜 2주가 걸리는가 — 불확실성의 터널과 우선순위의 소용돌이 (조정의 역풍 2편)
1편의 곱셈은 각자의 확률이 병가나 정전 같은 외부 사정으로 정해진다고 가정했다. 2편은 프로젝트 자체가 확률을 깎는 방식을 본다. Komoroske는 목표까지의 길을 터널로, 앞을 막는 불확실성을 바위로 그린다. 한 칸 전진은 한 시간이지만 바위 하나 치우는 데는 열 시간이 들고, 치우면 뒤에 또 바위가 있다. 여기에 '성공 가능성이 낮아 보이면 조금 덜 투자한다'는 합리적 판단이 겹치면 60%였던 성공률은 35%로 가라앉는다. 터널 시뮬레이터와 소용돌이 시뮬레이터로 그 과정을 직접 돌려 본다.
모두 유능한데 왜 조직은 느려지는가 — 점균류 조직론과 참여 확률의 곱셈 (조정의 역풍 1편)
빠르게 움직이던 회사가 어느 날부터 간단한 일에도 몇 주가 걸린다. 게으른 사람도, 무능한 사람도 없는데 그렇다. Alex Komoroske의 171장 슬라이드 「Coordination Headwind」는 이 현상을 점균류와 새떼, 그리고 곱셈 한 줄로 설명한다. 모두가 99% 확률로 제때 기여해도 열 명이 필요하면 성공률은 90%, 각자 다른 일이 쌓여 95%로만 내려가도 60%로 무너진다. 5편 시리즈의 첫 편에서 '조정의 역풍'이 무엇이고 왜 아무도 만들지 않았는데 생기는지, 인터랙티브 시뮬레이터 3종과 함께 짚는다.
Git, 이것만 알면 협업한다 7편 — Claude Code 시대의 git: 에이전트에게 맡기고, 사람이 감독하는 법
AI 코딩 에이전트가 파일을 고치고 git 명령까지 직접 실행하는 시대에는 git 기초가 오히려 더 중요해집니다. 시리즈 마지막 편에서는 Claude Code가 git을 어떻게 쓰는지(상태 확인·브랜치·커밋·PR·worktree·체크포인트)를 공식 문서로 확인하고, 사람이 감독할 지점과 위험한 명령, 에이전트에게 말하는 법, 1~6편 전체 치트시트까지 한 번에 정리합니다.