Claude Code를 사용하게 되면서, 구현에 걸리는 시간은 상당히 짧아졌습니다.

다만, 개발이 빨라지더라도 태스크를 생성하고, 착수 상태로 만들고, PR을 연결하고, 리뷰 중에 변경하고, 완료하는 등의 관리 작업은 남습니다. 한 번의 조작은 작더라도, 개발 도중에 몇 번이고 Linear를 여는 것은 은근히 번거롭습니다. 업데이트를 잊으면 보드와 실제 진척도도 어긋나게 됩니다.

현재는 Notion, Claude Code, Linear, GitHub를 연결하여, 사양 정리부터 구현, 리뷰, 태스크 완료까지 다음과 같이 진행하고 있습니다.

Notion에 사양을 정리한다
↓
Claude와 설계를 다듬는다
...

이 흐름에서 특히 편리했던 것이 Linear와 GitHub의 연동입니다.

GitHub 상에서 리뷰를 요청하면 Linear의 Issue가 In Review가 되고, PR을 머지(Merge)하면 Done이 됩니다. 개발자는 평소처럼 GitHub에서 작업하는 것만으로 Linear 측의 진척도도 따라갑니다.

이 기사에서는 현재의 개발 플로우와, 왜 자동화가 진행되어도 Linear에 Issue를 등록하고 있는지에 대해 정리합니다.

사양은 Notion에 모은다

인프라 구성이나 시스템 전체의 사양은 Notion에 정리하고 있습니다.

리포지토리(Repository) 내의 문서만으로 관리하는 방법도 있지만, 요구사항이나 설계 배경까지 포함하여 팀에서 공유하는 장소로서는 현재 Notion이 다루기 쉽다고 느끼고 있습니다.

Claude Code에는 Notion MCP를 연결해 두었습니다. 설계를 시작할 때는 대상 페이지를 읽게 한 뒤, 기존 코드도 확인하면서 대화를 나눕니다.

예를 들어, 다음과 같은 점을 먼저 확정합니다.

• 변경 목적
• 현재 구성에서 곤란한 점
• 채택할 설계
• 이번에 대응하지 않는 범위
• 이행 절차
• 동작 확인 방법

설계가 확정되면 그 내용을 구현 계획으로 옮깁니다.

Claude에게 구현 계획을 태스크 단위로 분해하도록 한다

구현 계획을 만든 후에는, Claude에게 Linear의 Issue 단위로 분해하도록 합니다.

사람이 모든 Issue를 처음부터 쓰는 것이 아니라, Claude가 사양서와 구현 계획을 읽고 구현 가능한 크기로 나누어 등록합니다.

실제 Issue는 대체로 다음과 같은 구성입니다.

## 작업 내용
- 변경 대상
- 구현 내용
...

중요한 것은 Issue를 단순한 작업명으로 만들지 않는 것입니다.

예를 들어 「디렉토리를 정리한다」라고만 하면 어디까지 변경해도 되는지 판단할 수 없습니다. 「이번에는 동작을 바꾸지 않고, 이동과 import 수정만 한다」와 같이, 변경해도 되는 범위와 변경해서는 안 되는 범위를 명시합니다.

Issue의 목적은 Claude를 위한 지시뿐만이 아니다

여기까지 Claude가 작업한다면, Linear를 거치지 않고 구현 계획을 그대로 Claude Code에 전달하면 될 것처럼 보이기도 합니다.

개인 개발이라면 그래도 문제없는 케이스가 있을 것이라고 생각합니다.

반면, 팀 개발에서는 다음 정보를 다른 멤버로부터 확인할 수 있어야 합니다.

• 현재 어떤 태스크를 진행 중인가
• 어디까지 완료되었는가
• 무엇이 리뷰 대기 중인가
• 다음에 착수할 수 있는 태스크는 무엇인가
• 사양과 구현이 어떤 PR과 연결되어 있는가

Claude Code의 세션 내에서만 작업을 진행하면, 구현하고 있는 본인은 알 수 있어도 다른 멤버로부터는 진척도가 보이지 않습니다.

Linear의 Issue는 Claude를 위한 입력인 동시에, 팀에게 진척도를 공개하는 단위가 됩니다.

즉, Issue를 만드는 목적은 태스크를 세밀하게 관리하는 것이 아니라, 개발 중인 상태를 팀이 볼 수 있게 하는 것입니다.

Claude Code에는 우선 구현 계획만 만들게 한다

Linear MCP를 사용하여 Claude Code에서 대상 Issue를 가져옵니다.

지시는 매번 길게 쓰지 않고, 모호한 점을 배제하여 구현 계획을 작성하는 skill이나 다음과 같은 내용입니다.

Linear의 JP-78을 가져와서, 관련 사양서와 기존 구현을 확인해 주세요.
아직 구현은 시작하지 말고, 다음을 포함하는 구현 계획을 작성해 주세요.
- 변경 대상
...

Issue를 읽자마자 바로 구현하게 하는 것이 아니라, 구현 계획을 한 번 확인합니다.

다만, 매번 세밀하게 계획을 다시 쓰는 운용 방식은 피하고 싶습니다. 사람이 리뷰하는 내용은 가급적 다음 판단으로 좁힙니다.

• Issue의 범위 안에 들어와 있는가
• 기존 사양을 깨뜨리는 변경이 포함되어 있지 않은가
• 테스트 방법이 타당한가
• 불필요한 리팩터링 (Refactoring)이 섞여 있지 않은가

Issue에 작업 내용, 제약 사항, 수락 조건(Acceptance Criteria)까지 작성되어 있다면, 대부분의 경우 계획을 읽고 승인하는 것만으로 충분합니다.

구현 계획의 리뷰를 없앤다기보다, 수정 작업이 아닌 승인 작업에 가깝게 만든다는 이미지입니다.

승인 후에는 subagent-driven 방식으로 구현한다

구현 계획을 승인한 후에는 Claude Code가 구현을 진행하도록 합니다.

현재는 조사, 구현, 테스트, 리뷰 등을 필요에 따라 서브 에이전트(Subagent)로 나누는 subagent-driven 방식을 사용하고 있습니다.

메인 컨텍스트(Context)만으로 모든 것을 처리하는 것보다, 조사 결과나 테스트 로그가 섞이지 않아 역할별로 확인하기가 더 쉽습니다.

구현 후에는 Claude 스스로도 차이점(Diff)을 리뷰하게 하고, 테스트 결과와 변경 내용을 정리하여 PR(Pull Request)을 생성하도록 합니다.

물론 Claude의 셀프 리뷰만으로 머지(Merge)하는 것은 아닙니다. 최종적인 PR 리뷰와 머지 판단은 사람이 수행합니다.

GitHub에서 개발하는 것만으로 Linear의 진척도가 업데이트된다

Linear의 Issue와 GitHub의 PR을 연결하면, PR 상태에 따라 Issue의 상태(Status)를 자동으로 업데이트할 수 있습니다.

제 환경에서는 다음과 같이 설정하고 있습니다.

PR로 리뷰 요청
↓
Linear: In Review
...

PR과 Issue를 확실하게 연결하기 위해, 브랜치 이름이나 PR 제목에는 Linear의 Issue ID를 포함합니다.

issue-78-reorganize-core-adapters

Claude Code에게 PR을 만들게 할 때도, Issue ID를 브랜치 이름이나 PR 제목에 넣도록 지시합니다.

이전에는 PR을 만든 후에 Linear를 열어 In Review로 변경하고, 머지 후에도 다시 한번 Done으로 변경해야 했습니다.

현재 개발자가 의식하는 조작은 다음 세 가지입니다.

구현하기
↓
리뷰 요청하기
...

태스크의 상태는 이러한 개발 행위로부터 자동으로 결정됩니다.

"PR을 만들었는데 Issue가 In Progress 상태로 남아 있다"거나 "머지되었는데 Done이 되지 않았다"와 같은 불일치도 발생하기 어려워졌습니다.

태스크 관리는 사라지지 않지만, 태스크 관리 작업은 줄일 수 있다

AI에 의한 구현이 진행되면 Issue 자체가 불필요해질 것처럼 보이기도 합니다.

실제로 팀 개발에서 태스크 관리가 불필요해지는 것은 아닙니다. 누가 무엇을 진행하고 있고, 어디에서 멈춰 있는지 공유하는 메커니즘은 필요합니다.

줄이고 싶은 것은 진척도를 공유하기 위해 사람이 동일한 정보를 반복해서 입력하는 작업입니다.

GitHub에는 이미 실제 개발 상황이 존재합니다.

• PR이 생성됨
• 리뷰가 요청됨
• 변경 사항이 승인됨
• PR이 머지됨

이 정보를 Linear와 연동하면, 사람이 수동으로 동일한 상태를 입력할 필요가 없습니다.

Linear는 팀이 진척도를 확인하는 장소로 남겨두되, 업데이트는 GitHub상의 개발 활동으로부터 자동으로 수행한다. 이러한 역할 분담이 현재의 운영 방식에 적합했습니다.

Issue를 만들 때 의식하고 있는 점

이 플로우에서는 Issue의 품질이 구현 계획의 품질로 직결됩니다. 특히 의식하고 있는 점은 다음 4가지입니다.

1. 하나의 PR로 확인할 수 있는 크기로 만들기

Issue가 너무 크면 구현 계획도 PR도 확인하기 어려워집니다.

"백엔드를 개선한다"가 아니라, "기존 동작을 바꾸지 않고 core와 adapters를 분리한다"와 같이 완료 조건을 판단할 수 있는 단위로 나눕니다.

2. 해야 할 일보다, 하지 말아야 할 일을 명시하기

Claude는 주변의 개선안까지 제안해 주기 때문에, 이번 대상에서 제외되는 범위를 명시해 두는 것이 더 안정적입니다.

## 대상 외
- API 사양 변경
- UI 변경
...

3. 수락 조건(Acceptance Criteria)을 확인 가능한 형태로 만들기

"적절하게 동작할 것"이 아니라, 커맨드, 테스트, 화면 조작 등 완료를 판단할 수 있는 조건을 작성합니다.

## 수락 조건
- `make server`가 성공할 것
- 기존의 메일 선택부터 실행까지의 조작이 동작할 것
...

4. 참조처 남기기

Issue만으로 모든 것을 설명하려고 하면 사양이 중복되어 업데이트 누락이 발생합니다.

상세한 설계는 Notion이나 리포지토리 내의 문서에 두고, Issue에는 구현에 필요한 요점과 참조처를 기재합니다.

주의사항

이 운영 방식이 모든 팀에 그대로 맞으리라는 보장은 없습니다.

예를 들어, 운영 환경 배포(Production Deploy)까지 완료하는 것을 기준으로 삼는 팀에서는, PR 머지 시점에서 Done

하는 것은 너무 빠릅니다. 그 경우에는, 머지(Merge) 시점에 Ready for Release 등으로 옮기고, 배포(Deploy) 완료 후에 Done으로 변경하는 것이 실제 상황에 더 부합합니다.

또한, GitHub 연동 자동 업데이트를 올바르게 작동시키려면, PR과 Linear Issue의 연결 규칙을 통일해 두어야 합니다. Issue ID를 누락하면 PR을 머지하더라도 상태(Status)는 업데이트되지 않습니다.

자동화하는 것 자체를 목적으로 삼지 말고, 팀에게 있어 "그 상태가 무엇을 의미하는가"를 먼저 결정해 두는 것이 중요합니다.

요약

현재의 개발 플로우에서는 Notion을 사양(Specification)의 저장소로, Linear를 팀에게 보이는 구현 단위로, GitHub를 실제 개발 상태의 저장소로 사용하고 있습니다.

Claude Code는 각각을 MCP를 통해 연결합니다.

Notion
팀에게 보이는 사양과 설계
↓
...

AI가 코드를 작성하게 되더라도, 팀과 진척도를 공유해야 할 필요성은 사라지지 않습니다.

다만, 이를 위해 개발자가 Issue의 상태를 계속해서 수동으로 업데이트할 필요는 없습니다.

평소처럼 구현하고, 리뷰를 요청하고, PR을 머지합니다. 그 결과가 Linear에 자동으로 반영되게 된 이후로는, 태스크 관리(Task Management)를 의식하며 화면을 왔다 갔다 하는 일이 없어졌습니다.

제가 이 연동에서 느끼는 가장 큰 가치는, AI가 구현을 해준다는 점뿐만 아니라, 개발의 흐름과 팀의 진척도가 자연스럽게 일치한다는 것입니다.

Discussion