도입

Claude Code를 위해, 세션 내용을 Zenn 기사 초안으로 변환하는 신규 스킬 「article-writeup」을 만들었다. 트리거 문구를 말하면, Claude Code가 대화 내용을 요약하고, 서브 에이전트(sub-agent)에게 초안 생성을 위임하며, 인간의 확인을 거쳐 Zenn에 push하는 것까지 일련의 과정을 자동화하는 메커니즘이다. 지금 바로 읽고 있는 이 기사도 그 스킬로 초안이 작성되었다 (메타적인 이야기지만 사실이다).

이 스킬을 만들 때, 제로 베이스에서 즉흥적으로 구현하는 것이 아니라, Claude Code의 「superpowers」 플러그인이 제공하는 스킬군을 통틀어 사용해 보기로 했다. superpowers는 요구사항 정의 · 계획 · 구현 · 리뷰 · 브랜치 운영 등, 개발의 각 페이즈에 대응하는 스킬을 하나로 묶은 플러그인이다. 구체적으로는 brainstorming (요구사항을 대화적으로 구체화) → writing-plans (구현 계획을 수립) → subagent-driven-development (서브 에이전트에게 구현을 위임하고 리뷰 사이클을 돌림) → git worktree (작업 브랜치를 분리) → finishing-a-development-branch (PR을 생성하여 머지) 순으로 진행했다. 요구사항 정의부터 공개까지 일관된 「형식」으로 완수하면 어떻게 될 것인가, 라는 시도이기도 하다.

결론부터 말하자면, 이 형식에 따라 진행함으로써 구현이 완료되기 전 단계에서 여러 개의 실질적인 버그를 검출 및 수정할 수 있었다. 이하, 그 흐름과 막혔던 포인트들을 적어 나간다.

본문

창조적인 작업은 brainstorming부터 시작한다

「article-writeup 스킬 구현을 시작하고 싶어」라고 말했을 뿐인데, Claude Code는 갑자기 코드를 쓰기 시작하지 않았다. 신규 스킬 생성은 창조적인 작업이라는 판단하에, 먼저 brainstorming 스킬을 기동하여 기존 리포지토리의 스킬 구성 (skills/<name>/SKILL.md 형식)을 조사한 후, AskUserQuestion을 사용하여 요구사항을 대화적으로 구체화해 왔다.

이 상호작용을 통해 결정된 주요 사항은 다음과 같다.

• v1은 풀 스코프(full scope)로 한 번에 만든다 (트리거 감지 → 서브 에이전트 위임 → 초안 생성 → style-guide 육성 → 인간 확인 → Zenn push, 이 일련의 흐름을 처음부터 관통함)
• Zenn로의 공개는 GitHub 리포지토리 연동 방식으로 한다. articles/<slug>.md에 frontmatter를 붙여 배치하는 형태
• 설정 파일의 위치는 XDG Base Directory 규약에 따라 ~/.config/article-writeup/config.yml로 한다. 이유는 단순하게, 자신의 홈 디렉토리 하위는 chezmoi로 관리하고 있어 chezmoi의 관리 대상에서 제외하고 싶었기 때문

요구사항을 일문일답 형식으로 그 자리에서 결정해 가는 스타일은, 나중에 「왜 이 사양으로 했었지?」라며 헤매지 않아도 된다는 점에서 나쁘지 않았다.

여담이지만, 이 브레인스토밍 도중에 Esc 키를 연타해 버려서 「대화를 다시 시작해 버렸을지도 모른다」며 당황했던 장면이 있었다. 확인해 보니 그 시점에는 아직 파일 쓰기가 발생하지 않았고, git status도 클린했기 때문에 실질적인 피해는 없었다. 파일 쓰기 전 단계라면 약간의 조작 실수는 되돌릴 수 있다는 점은 기억해 두어도 손해 볼 것이 없다.

설계서와 구현 계획을 커밋한 후 작업을 분리한다

요구사항이 확정된 후, 전체 아키텍처 · 파일 구성 · 서브 에이전트로의 위임 설계를 Claude Code가 제시하였고, 이쪽에서 승인한 뒤 설계서를 docs/superpowers/specs/ 하위에 작성하여 커밋했다. 이 후 한 번 「시간이 없으니 중단하겠다」라고 말하여 작업을 멈추고, 며칠 뒤 「재개해 줘」라고 전달하여 재개했다. 설계서를 파일로 남겨 커밋해 둔 덕분에, 재개 시에 문맥을 다시 설명할 필요가 없었던 점은 좋았던 부분이다.

이어서 writing-plans 스킬로 구현 계획을 4개의 태스크로 분할했다.

• 설정 템플릿과 style-guide 초판
• SKILL.md 본체
• 대표 시나리오의 트레이스 검증
• APM을 통한 배포 및 배치 확인

이 과정에서 계획 파일 내의 Markdown 코드 펜스(code fence)가 중첩되어 깨져 있는 것을 발견했다. 바깥쪽을 4개의 백틱(backtick)으로 설정함으로써 해결했다. 계획서와 같이 「코드 블록 안에 코드 블록의 예시를 쓰는」 문서를 만들 때는, 펜스의 중첩에 주의하는 것이 좋을 것 같다.

구현은 main 브랜치에 직접 수행하지 않고, git worktree를 사용하여 작업을 분리하는 방침으로 정했다. 다만 worktree를 만들기 전에 설계서와 계획서의 커밋이 아직 GitHub에 push되지 않았다는 사실을 깨달았다. worktree는 별도의 디렉토리에서 main을 참조하는 형태가 되기 때문에, 먼저 원격(remote)으로 push한 뒤에 worktree를 생성해야 한다. 이 순서를 틀리면 worktree 측에서 원격의 최신 상태가 보이지 않는데, 은근히 빠지기 쉬운 함정(ハマるポイント)이라고 생각한다.

3단계 리뷰 사이클에서 발견한 4개의 버그

이 부분이 가장 쓰고 싶었던 내용이다. subagent-driven-development 스킬에 따라 4개의 태스크를 순서대로 실행했다. 각 태스크는 다음의 3단계 사이클로 진행한다.

• implementer 서브 에이전트가 구현한다
• spec-reviewer 서브 에이전트가 사양 준수 관점에서 리뷰한다
• code-quality-reviewer 서브 에이전트가 코드 품질 관점에서 리뷰한다

지적이 나올 때마다 수정용 서브 에이전트를 기동하여 다시 리뷰를 돌린다. 이 사이클을 돌리는 도중에 실제로 4개의 결함이 발견되었다.

• 설정 경로의 존재 체크가 비대칭이었다 (어떤 경로에서는 존재 확인을 하고 있는데, 다른 유사한 경로에서는 확인하지 않는 일관성 결여)
• Zenn의 슬러그(slug) 길이 요구사항(12~50자)을 충족하지 못하는 케이스에 대한 대처가 누락되었다
• 초안에서 Zenn 공개판을 만들 때, 「제목 안(タイトル案)」 섹션을 제거하는 처리 기술이 누락되었다
• Zenn의 슬러그가 우연히 충돌했을 때, 기존 기사를 무단으로 덮어써 버리는 리스크가 있었다

모두 「동작은 하지만, 경계 조건(boundary condition)이나 에지 케이스(edge case)를 밟으면 망가지는」 타입의 결함으로, 구현 담당 서브 에이전트 단독으로는 알아채기 어려운 것들이었다. 사양 리뷰와 코드 품질 리뷰의 역할을 분담하여 나누었기에 잡아낼 수 있었다는 인상이 강하다. 특히 슬러그 충돌 시의 무단 덮어쓰기는, 알아채지 못하고 릴리스했다면 은근히 골치 아픈 사고가 되었을 것이기에 리뷰 사이클을 거치는 가치를 실감한 부분이었다.

모두 구현 완료 전, 즉 PR을 내기 전 단계에서 검출 및 수정할 수 있었다.

PR 머지(Merge)와 APM 배포에서의 함정

모든 태스크 완료 후, finishing-a-development-branch 스킬로 PR을 작성했다. 이 리포지토리에는 테스트 스위트(test suite)가 없었기 때문에, 테스트 실행 단계는 해당 없음으로 간주하고 진행했다. 「PR을 리뷰·머지해 주세요」라고 전달하자, gh pr diff로 차분을 직접 확인한 뒤 머지까지 완료해 주었다.

마지막으로 보류하고 있던 Task 4, APM을 통한 글로벌 배포 확인을 실행했다. 여기서 작은 배움이 있었다. apm install --global을 실행했을 뿐으로는 apm.lock.yaml이 오래된 커밋에 고정된 상태로 남아 있어, 새로 추가한 article-writeup 스킬이 반영되지 않았던 것이다. apm update --global을 실행하고 나서야 비로소 리포지토리의 최신 커밋으로 업데이트되어, 스킬이 실제로 배포되었다.

install과 update가 별개의 명령어로 나뉘어 있는 툴에서는, 「한 번 install했으니 최신 상태일 것」이라는 짐작은 위험하며, 변경 사항을 반영하고 싶을 때는 update 계열의 명령어를 명시적으로 호출해야 한다는, 당연하지만 잊기 쉬운 포인트였다.

요약

신규 스킬을 하나 완성할 때, brainstorming → writing-plans → subagent-driven-development → git worktree → finishing-a-development-branch라는 superpowers 스킬군을 통틀어 사용하면, 요구사항 정의부터 PR 머지까지 일관된 패턴으로 진행할 수 있다. 특히 구현 태스크마다 implementer → spec-reviewer → code-quality-reviewer라는 3단계 리뷰 사이클을 돌리는 부분은 효과가 매우 커서, 이번 세션만으로도 경계 조건의 간과나 무단 덮어쓰기 리스크와 같은 실질적인 버그를 릴리스 전에 여러 개 검출 및 수정할 수 있었다.

세세한 배움으로는, 파일 쓰기 전이라면 Esc를 연타하여 대화를 되돌려도 실질적인 해가 없다는 점, worktree를 만들기 전에는 원격으로의 push를 마쳐둘 필요가 있다는 점, APM과 같은 툴에서는 install과 update가 별개이며 변경을 반영하려면 명시적으로 update를 호출해야 하는 경우가 있다는 점도 기록해 두고 싶다.

일관된 형식을 따라 진행하는 것이 다소 번거롭게 느껴지는 순간도 있었지만, 리뷰 사이클(review cycle)에서 찾아낸 버그의 수를 고려하면, 적어도 이번과 같은 "나중에 수정하기 어려운 설계 판단을 포함하는 신규 스킬 생성"에서는 이 형식을 끝까지 유지할 가치가 있었다고 생각한다.

이러한 세션 운영 기록은 앞으로도 이 스킬 자체를 사용하여 계속 작성해 나갈 예정이다. 다음에는 어떤 난관에 부딪히게 될지 기대된다.

Discussion