OpenClaw Conventional Commits 스킬 가이드

OpenClaw Conventional Commits 스킬 개요

Conventional Commits 스킬은 구조화되고 스펙을 준수하는 커밋 메시지를 OpenClaw 워크플로에 도입합니다. 커밋 메시지를 처음부터 작성하거나 Conventional Commits 스펙을 외우는 대신, OpenClaw 에이전트에게 스테이징된 변경 사항을 기반으로 메시지를 생성하거나 검증하도록 요청하면 됩니다.

Conventional Commits는 커밋 메시지 위에 구축된 경량 규칙으로, 명확하고 기계 판독 가능한 히스토리를 제공합니다. 수천 개의 오픈소스 및 엔터프라이즈 프로젝트에서 자동 변경 로그, 시맨틱 버전 관리, 릴리스 도구를 지원합니다. 이 OpenClaw 스킬을 사용하면 인지적 부담 없이 이러한 이점을 누릴 수 있습니다.

일반적인 워크플로:

1. git add로 변경 사항을 스테이징합니다.
2. OpenClaw에게 커밋 메시지 작성을 요청합니다.
3. 에이전트가 diff를 분석하고, 올바른 유형(feat, fix, docs 등)을 결정한 후, 적절한 형식의 메시지를 제안합니다.

Conventional Commits 스킬 사전 요구 사항

Conventional Commits 스킬을 설치하기 전에 다음을 확인하세요:

• OpenClaw 설치 및 실행 중 (v1.0+)
• Git 설치됨 (v2.20+) — 공식 다운로드
• git init으로 초기화된 프로젝트 저장소
• clawhub CLI 설치됨

환경 확인:

# OpenClaw 버전 확인
openclaw --version

# Git 버전 확인
git --version

# Git 저장소 내에 있는지 확인
git status

Conventional Commits 스킬 설치 방법

한 줄의 명령으로 Conventional Commits 스킬을 설치합니다:

npx clawhub@latest install conventional-commits

설치 확인:

clawhub list

설치된 스킬 목록에 conventional-commits가 표시되어야 합니다. 이 스킬은 바로 사용 가능합니다 — API 키나 외부 서비스가 필요 없습니다.

Conventional Commits 스킬 구성

이 스킬은 최소한의 구성만 필요합니다. 스테이징된 Git 변경 사항을 읽고 Conventional Commits 스펙에 따라 메시지를 포맷합니다. 팀의 규칙에 맞게 동작을 커스터마이징할 수 있습니다.

커밋 유형

이 스킬은 표준 Conventional Commits 유형을 인식합니다:

| 유형 | 사용 시점 | |------|----------| | feat | 사용자 대상 새 기능 | | fix | 버그 수정 | | docs | 문서만 변경 | | style | 포맷팅, 세미콜론 누락 (로직 변경 없음) | | refactor | 기능이나 수정 없는 코드 재구조화 | | perf | 성능 개선 | | test | 테스트 추가 또는 업데이트 | | chore | 빌드 프로세스, 의존성 업데이트, 도구 설정 | | ci | CI/CD 설정 변경 |

스코프 커밋

모노레포 및 대규모 프로젝트를 위한 스코프 커밋 메시지를 지원합니다:

feat(auth): add OAuth2 login flow
fix(api): handle null response from payment endpoint
docs(readme): update installation instructions

프로젝트 설정에서 허용되는 스코프를 정의하여 기여자 간 일관성을 유지할 수 있습니다.

Conventional Commits 스킬 사용 예시

1. 스테이징된 변경 사항에서 커밋 메시지 생성

사용자: "스테이징된 변경 사항에 대한 커밋 메시지를 작성해 줘."

에이전트가 git diff --staged를 확인하고, 새 API 엔드포인트를 추가한 것을 식별하여 반환합니다:

feat(api): add user profile endpoint

Implement GET /api/users/:id/profile with authentication
middleware and response caching.

수락, 편집 또는 다른 톤이나 스코프로 재생성을 요청할 수 있습니다.

2. 기존 커밋 메시지 검증

사용자: "이 커밋 메시지가 규칙을 따르는지 확인해 줘: 'Updated the login page'"

에이전트가 메시지를 분석하고 구체적인 피드백을 반환합니다:

• 유형 접두사 누락 — feat:, fix: 또는 다른 유효한 유형으로 시작해야 함
• 과거형 사용 ("Updated") — 규칙에서는 명령형 ("update") 권장
• 수정 제안: fix(auth): update login page layout

3. 최근 커밋 일괄 검증

사용자: "이 브랜치의 최근 10개 커밋 메시지를 검증해 줘."

에이전트가 최근 히스토리를 확인하고, 규칙을 준수하지 않는 커밋을 표시하며 각각에 대한 수정 대안을 제공합니다. 기능 브랜치를 main에 병합하기 전에 유용합니다.

4. 브레이킹 체인지 커밋 생성

사용자: "이것을 브레이킹 체인지로 커밋해 줘 — v1 API를 제거했어."

에이전트가 적절한 브레이킹 체인지 커밋을 포맷합니다:

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: All /api/v1/* routes have been removed.
Consumers must migrate to /api/v2/* before upgrading.

! 접미사와 BREAKING CHANGE 푸터가 모두 포함되어 semantic-release 및 standard-version 등의 도구와의 호환성을 보장합니다.

보안 및 모범 사례

Conventional Commits 스킬은 OpenClaw 생태계에서 가장 안전한 스킬 중 하나입니다 — 텍스트 포맷팅과 검증만 수행하며, 외부 API 호출이나 로컬 Git 저장소 외부의 쓰기 작업이 없습니다.

최상의 경험을 위해 다음 가이드라인을 따르세요:

• 커밋 전 검토. 생성된 메시지를 승인하기 전에 반드시 읽어보세요. 에이전트는 diff에서 의도를 추론하지만, 컨텍스트를 가장 잘 아는 것은 사용자입니다.
• 일관된 스코프 사용. 프로젝트의 허용 스코프 목록을 정의하고 팀과 공유하여 스코프 혼란을 방지하세요.
• CI 검증과 결합. commitlint 같은 도구로 CI 파이프라인에서 Conventional Commits를 강제하여, 스킬을 건너뛴 수동 커밋을 포착할 수 있습니다.
• 프리커밋 훅 활성화. husky 또는 lefthook을 사용하여 커밋 메시지 검증을 자동으로 실행하세요.

일반적인 오류 해결

"Not a git repository"

이 스킬은 Git으로 초기화된 디렉터리 내에서 실행해야 합니다.

# 새 저장소 초기화
git init

# 또는 기존 프로젝트로 이동
cd /path/to/your/project

"No staged changes found"

의미 있는 커밋 메시지를 생성하려면 스테이징된 변경 사항이 필요합니다.

# 특정 파일 스테이징
git add src/feature.ts

# 또는 모든 변경 사항 스테이징
git add -A

"Unable to determine commit type"

diff가 매우 크거나 관련 없는 파일이 많을 때 발생할 수 있습니다. 더 작고 집중된 변경 세트를 스테이징하거나, 유형을 수동으로 지정하세요:

사용자: "이 변경 사항에 대한 refactor 커밋 메시지를 작성해 줘."