AI 주도 웹 개발 파이프라인: Claude Code 활용 가이드

1주 차 테크노트 주제 : Claude Code 활용 웹 개발 파이프라인

사전 직무 교육 때 학습한 Claude Code를 활용한 AI 주도 웹 개발 파이프라인을 다시 한번 따라 하고, 정리해서 앞으로의 프로젝트 과정에서 사용할 수 있도록 정리합니다.

- 준비물 : 컴퓨터(여기서는 mac 환경 기준), Claude Code를 사용할 수 있는 계정

- Speckit 기반 웹 서비스 개발 워크플로우를 따라서 개발을 배웠고, 여기서도 Speckit을 기반으로 작성됩니다.

2. Canvas 작성

캔버스(Canvas)란 사업 또는 연구를 위한 아이디어를 구체화해서 최대한 명확하고 구체적인 정의서의 형태를 말합니다. 여기서는 다른 웹에서 쉽게 작성했지만, 우리가 한 비즈니스용 캔버스는 아래와 같이 개요와 11개의 칸으로 이루어져서 구체화하는 방식이었습니다.

개요: 미션 / 핵심 활동 / 핵심 파트너 / 핵심 장벽 / 핵심 이네이블러 / 핵심 데이터 / 가치 제안 / 부정적 영향 / 혜택 / 비용 / 수익

각각의 칸을 최대한 구체적으로 작성하는 게 중요합니다. 데이터 주도 비즈니스 모델의 캔버스로, 주제에 따라 캔버스의 형태는 달라질 수 있으니 자신에 맞는 틀을 찾아 구체화하는 과정이 중요합니다.

3. 서비스 명세 구체화

위 명령어로 동작하는 명세 구체화 과정입니다. 개인적으로는 노션에 작성한 뒤 .md 파일로 저장하고, 저장된 프로젝트 디렉토리에서 실행하면 됩니다.

대개는 실행할 때 명령어-참조 파일-구체적인 명령으로 구성하는 것 같습니다.

예시: /speckit.specify 'Intent-Specify.md' 작성한 캔버스를 토대로 프로젝트 서비스 명세(Specification)를 상세하게 생성합니다.

4. 명세 오류 검토 및 수정

생성된 명세에 논리적 오류나 누락이 없는지 재검토하며 수정하는 과정입니다. 몇몇 파일이 생성될 수 있고, 구체화 후 캔버스와 대조 및 평가하면서 오류를 잡는 디버깅 과정이라고 생각하면 됩니다.

5. 프로젝트 세부 계획 수립

검증된 명세를 바탕으로 구체적인 빌드 계획을 세우고, 어떤 툴과 기술을 이용하여 서비스를 구체화할 것인지 정하는 단계입니다.

예시: /speckit.plan 'intent-plan.md' 수정된 명세를 기반으로 구체적인 빌드 계획을 세웁니다.

6. 서비스 구현 시 task 분할

실제 구현 바로 전 단계로, 계획한 작업들을 체계적으로 분할하고 준비합니다. 이때 [프론트엔드, 백엔드, 도메인]의 3대 요소가 명확하게 반영되었는지 확인해야 합니다.

예시: /speckit.tasks 'Intent-Tasks.md' 파일을 참조하여 바로 구현 가능한 서비스 task를 계획합니다.

7. 서비스 구현 및 수정

앞에서 만든 가이드라인 파일들을 참조하여 실제 코드를 구현하는 과정입니다. 외부 인터넷과 연동할 수 있도록 지정된 포트와 도메인을 명확하게 명시하는 것이 중요합니다.

예시: /speckit.implement 'task.md' 파일을 참조하여 구현하라. 웹서비스 front-end, backend는 각각 1234, 5678이다.

8. 서비스 정상화 및 자가 루프 테스트

도메인 접속 시 화면이 안 뜨는 현상 등을 방지하기 위해 웹 서버가 정상 작동하고 누구나 접근할 수 있을 때까지 시스템이 에러를 찾고 자동으로 수정 보완하도록 루프(/loop) 명령어를 수행하는 과정입니다.

예시: 구현한 결과 서비스를 정상화하라. 123.com 도메인으로 누구나 접근 가능한지 테스트하라.

9. 버전 관리 및 git push

중간중간 해도 되지만, 결국 깃에 코드류만 올리고 싶으면 이때 저장소명/리포지토리 주고 로그인한 뒤 push 하게 하면 됩니다. 전부 라벨링도 잘 해서 깃에 올려주면 됩니다.

10. (옵션) 서버 관리용 스위치 스크립트 제작

배포 후 효율적인 유지 보수를 위해 프론트엔드, 백엔드, 도메인 상태를 체크하고 제어할 수 있는 쉘 스크립트 제어기를 생성하는 과정입니다.

예시: 현재 정상화되어있는 서비스의 시작과 정지, 재시작을 다음 스크립트로 간결하게 만들어줘.

정리

Canvas 작성 (최대한 명확하고 구체적으로) / speckit.specify로 구체화 / speckit.clarify로 명세 오류 탐지 및 수정 / speckit.plan으로 세부 계획 / speckit.tasks로 구현 task 계획 / speckit.implement로 구현(웹서비스 포트, 도메인 등 명확히 제공) / 수정 / 서비스 정상화 / Git push / Kill code(스위치) 제작