Taskfile, Pre-commit Hooks, Git Worktrees를 활용하여 신뢰할 수 있는 개발 워크플로우 구축하기

강력한 개발 워크플로우 (Developer Workflow)는 단순히 "더 빠르게 움직이는 것"에 관한 것이 아니라, 작은 마찰 요인들이 버그, 컨텍스트 손실(Context loss), 또는 반복적인 설정 실수로 이어지기 전에 이를 제거하는 것에 관한 것입니다. 이 가이드는 Taskfile, pre-commit hooks, 그리고 Git worktrees를 결합하여 실제 프로젝트에서 사용할 수 있는 하나의 실용적인 시스템을 구축하는 방법을 보여줍니다.

이 워크플로우가 효과적인 이유

핵심 아이디어는 일반적인 경로를 명확하게 만드는 것입니다. 즉, 작업을 실행하기 위한 하나의 명령, 커밋 전의 하나의 자동화된 게이트(Gate), 그리고 작업 단위당 하나의 격리된 디렉토리(Directory)를 갖는 것입니다. Taskfile는 프로젝트 명령어를 표준화하여 사람들이 긴 셸 스니펫 (Shell snippets)을 기억할 필요가 없도록 도와줍니다. Pre-commit hooks는 포맷팅 (Formatting) 및 품질 문제를 저장소에 들어가기 전에 잡아내며, Git worktrees를 사용하면 끊임없이 스태시 (Stash)하거나 폴더를 전환할 필요 없이 여러 브랜치 (Branches)에서 작업할 수 있습니다.

이것이 중요한 이유는 많은 워크플로우 문제가 사실 조정 (Coordination) 문제이기 때문입니다: "어떤 명령어를 실행해야 하지?", "이걸 포맷팅했나?", "두 개의 수정 사항을 어떻게 분리해서 유지하지?". 이러한 답변들이 저장소에 체크인된 파일에 인코딩되어 있을 때, 그 프로세스는 당신과 다른 모든 사람에게 반복 가능해집니다.

1단계: 태스크 러너 (Task runner) 생성하기

가장 자주 사용하는 명령어들을 Taskfile.yml에 넣는 것부터 시작하세요. Task는 코드 생성 (Code generation), 포맷팅 (Formatting), 린팅 (Linting), 테스트 (Tests)와 같은 반복적인 동작들을 연결하는 동시에, 프로젝트 어디에서나 워크플로우를 쉽게 찾을 수 있도록 설계되었습니다. 좋은 Taskfile는 짧고, 읽기 쉬우며, 예측 가능해야 합니다.

version: '3'

tasks:
...

이것이 준비되면, 정확한 패키지 매니저 (Package-manager) 명령어를 기억하는 대신 task setup, task lint, 또는 task ci를 실행할 수 있습니다. 진정한 이점은 일관성입니다. 새로운 팀원들과 미래의 당신은 매번 동일한 진입점 (Entry points)을 갖게 됩니다.

실용적인 규칙

태스크(Task) 이름은 안정적으로 유지하고 설명은 명확하게 작성하세요. Taskfile의 내장된 설명(descriptions) 기능은 사용 가능한 명령어를 더 쉽게 찾을 수 있게 해주며, 이는 새로운 기여자(contributors)가 프로젝트의 워크플로우 (workflow)를 빠르게 이해하는 데 도움을 줍니다. 만약 특정 명령어를 입력하는 것이 번거롭거나 잊어버리기 쉽다면, 반드시 Taskfile에 포함시켜야 합니다.

Step 2: pre-commit 체크 추가하기

Pre-commit hooks는 로컬 품질 관리 (quality control)를 위한 안전망입니다. 커밋 (commit)이 완료되기 전에 자동으로 실행되기 때문입니다. 이는 포매팅 (formatting), 린팅 (linting), 작은 검증 스크립트 (validation scripts), 그리고 가벼운 테스트 (tests)와 같이 빠른 체크를 수행하는 데 가장 적합합니다. 목표는 CI (지속적 통합)를 대체하는 것이 아니라, 명백한 문제들이 사용자의 컴퓨터를 떠나기 전에 차단하는 것입니다.

간단한 .pre-commit-config.yaml 파일은 다음과 같은 모습일 수 있습니다:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
...

클론 (clone)할 때마다 한 번씩 훅 (hooks)을 설치하고 활성화하세요:

pre-commit install
pre-commit run all-files

좋은 훅 세트는 일반적인 작업 중에 거의 의식하지 못할 정도로 충분히 빨라야 합니다. 만약 특정 체크가 느리다면, 커밋 (commit)의 반응성을 유지할 수 있도록 Taskfile이나 CI로 옮기세요.

Step 3: 병렬 작업을 위한 worktrees 사용하기

Git worktrees를 사용하면 하나의 저장소 (repository)에서 여러 브랜치 (branches)를 별도의 디렉토리 (directories)에 체크아웃 (checked-out)할 수 있습니다. 이는 버그를 수정하고, PR (Pull Request)을 리뷰하며, 동시에 새로운 기능을 시작해야 하는 상황에서 완벽한 도구가 됩니다. 변경 사항을 반복적으로 스태시 (stashing)하는 대신, 각 작업을 격리된 상태로 유지하며 각각의 에디터 (editor) 창에서 열어둘 수 있습니다.

간단한 설정은 다음과 같습니다:

git worktree add ../project-auth feature/auth
git worktree add ../project-fix-login hotfix/login-edge-case
git worktree list

폴더 이름을 브랜치 (branch)나 작업 (task) 이름으로 지정하여 무엇이 들어있는지 명확히 하는 것이 좋은 습관입니다. 작업이 끝나면 다음과 같이 정리하세요:

git worktree remove ../project-auth
git worktree prune

이 방식은 브랜치별로 별도의 터미널 (terminals)이나 AI 도구들을 사용할 때 특히 유용하며, 브랜치 간의 실수나 워처 충돌 (watcher collisions)을 줄여줍니다.

Step 4: 조각들을 연결하기

이러한 도구들이 서로를 보완할 때 워크플로우는 강력해집니다. Taskfile은 단일 명령 인터페이스를 제공하고, pre-commit은 로컬 품질을 강제하며, worktrees는 각 작업에 독립적인 공간을 부여합니다. 즉, 새로운 worktree를 열고, task setup을 실행한 뒤, 변경 사항을 적용하고, 훅 (hook) 검사를 통과한 후에만 커밋할 수 있음을 의미합니다.

전형적인 하루의 모습은 다음과 같을 수 있습니다:

기능을 위한 worktree를 생성합니다.
해당 디렉토리에서 task setup을 실행합니다.
작은 단계별로 변경 사항을 적용합니다.
task lint와 task test를 실행합니다.
커밋을 수행하여, pre-commit이 포맷팅 어긋남 (formatting drift)을 잡아내도록 합니다.
머지 (merge) 후 worktree를 삭제합니다.

이러한 패턴은 집중적인 작업 중에 내려야 하는 결정의 수를 줄여주며, 이는 종종 생산성 향상이 실제로 발생하는 지점이기도 합니다.

Step 5: 태스크와 훅을 빠르게 유지하기

빠른 피드백은 사람들이 실제로 사용하는 워크플로우와 우회해버리는 워크플로우를 가르는 차이점입니다. 훅 체인 (hook chain)을 짧게 유지하고, 비용이 많이 드는 통합 테스트 (integration tests)를 커밋 경로에 밀어 넣는 것을 피하십시오. 로컬 루프 (local loop)가 긴밀하게 유지될 수 있도록, 더 무거운 검사들은 task ci나 실제 CI 파이프라인 (CI pipeline)을 위해 남겨두어야 합니다.

유용한 분할 방식은 다음과 같습니다:

pre-commit: 포맷팅 (formatting), 린팅 (linting), 파일 위생 (file hygiene), 아주 작은 검증 검사.
Taskfile 로컬 명령: 설정 (setup), 테스트 (test), 빌드 (build), 생성 (generate), CI 시뮬레이션.
CI: 전체 테스트 매트릭스 (test matrix), 배포 검사, 그리고 더 느린 검증.

만약 어떤 검사가 명확하지 않은 이유로 계속 실패한다면, 단순화하십시오. 신뢰할 수 있지만 약간 덜 야심 찬 워크플로우가, 개발자들이 우회해버리는 영리한 워크플로우보다 훨씬 낫습니다.

예시 프로젝트 설정

다음은 많은 JavaScript 또는 TypeScript 저장소에 바로 적용할 수 있는 간결한 패턴입니다:

### Taskfile.yml
version: '3'

...

### .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
...

### 클론(clone)당 1회 실행
pre-commit install

...

이를 통해 기억력이나 암묵적 지식 (tribal knowledge)에 의존하지 않고도 체크아웃 (checkout)부터 커밋까지 깨끗한 경로를 확보할 수 있습니다.

흔한 실수들

한 가지 실수는 저장소 내의 모든 셸 스크립트(shell script)를 Taskfile의 쓰레기통처럼 사용하는 것입니다. 더 나은 접근 방식은 사람들이 실제로 자주 필요로 하는 명령만 노출하고, 이름을 명확하게 유지하는 것입니다. 또 다른 실수는 pre-commit을 너무 무겁게 만드는 것인데, 이는 no-verify 습관으로 이어져 도입 취지를 무색하게 만듭니다. 세 번째 실수는 정리 없이 수많은 워크트리(worktrees)를 생성하는 것이며, 이는 파일 시스템과 여러분의 정신적 모델(mental model)을 모두 어지럽게 만듭니다.

좋은 워크플로우란 단순히 도구를 위한 도구를 추가하는 것이 아닙니다. 반복되는 결정을 기본값(defaults)으로 전환하여, 코드 자체에 더 많은 주의를 기울일 수 있도록 만드는 것입니다.

간단한 도입 계획

기존 저장소에 이를 도입하려는 경우, 다음 순서를 따르십시오. 먼저 설정(setup), 린트(lint), 테스트(test), 그리고 CI와 유사한 체크(CI-like checks)를 위한 Taskfile 명령을 추가합니다. 그다음, 포맷팅(formatting)과 명백한 위생(hygiene)을 강제하는 작고 빠른 pre-commit 설정을 추가합니다. 마지막으로, 병렬 브랜치(parallel branches)나 핫픽스(hotfixes)를 위해 워크트리(worktrees)를 사용하기 시작하고, 해당 명령들을 저장소의 README에 문서화합니다.

이러한 단계적 도입은 도입 비용을 낮게 유지하며 각 개선 사항을 쉽게 평가할 수 있게 해줍니다. 워크플로우가 저장소 내에서 가시화되면, 그것은 개인의 선호도가 아닌 코드베이스의 일부가 됩니다.

Rizwan Saleem | https://rizwansaleem.co

Taskfile, Pre-commit Hooks, Git Worktrees를 활용하여 신뢰할 수 있는 개발 워크플로우 구축하기

요약

핵심 포인트

Taskfile, Pre-commit Hooks, Git Worktrees를 활용하여 신뢰할 수 있는 개발 워크플로우 구축하기