---
name: golang-project-guide
description: 표준 라이브러리 중심 경량 Go CLI 도구의 구조·패키지·디스패처 규칙과 Go 공식 스타일(Effective Go / Google Go Style Guide) 가이드. Go 코드(cmd 진입점, internal 패키지, 커맨드 enum, flag 파싱, 외부 API 클라이언트, 설정, 출력/테이블)를 새로 만들거나 수정할 때 참고한다. cmd+internal 레이아웃, 커맨드 enum + flag 디스패처, 클라이언트 팩토리 + 값타입 모델/뷰 융합, 에러 처리·네이밍·리시버 규칙, 테이블 주도 테스트 포함.
user-invocable: true
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(ls *)
  - Bash(find *)
  - Bash(grep *)
---

# golang-project-guide — Go CLI 프로젝트 구조 & 스타일 가이드

표준 라이브러리 중심 경량 Go CLI 코드를 작성·수정할 때 이 스킬의 규칙을 그대로 따른다.
프레임워크(cobra 등)를 임의로 도입하지 않고 정해진 구조를 유지한다.

## 사용법

1. **작업 시작 전 전체 가이드를 읽는다**: `Read ./golang.md` (같은 디렉터리).
2. 아래 요약으로 방향을 잡고, 세부는 `golang.md`의 해당 절을 참조한다.
3. 새 커맨드/도메인이면 `golang.md` 하단 **구현 체크리스트**를 실제로 훑는다.

## 빠른 요약 (세부는 golang.md 참조)

- **스택**: Go 1.21+, 표준 `flag`(cobra 미사용), `pkg/errors`, `yaml.v3`. 의존성 최소화. → golang.md §1
- **구조**: `cmd/main.go`(얇은 조립/디스패치) + `internal/`(모든 로직, 외부 import 불가). 패키지명=디렉터리명, 짧은 소문자. → §2
- **아키텍처**: 커맨드 enum(`command`) + `flag` 파싱(`argument`) + `main.go`의 단일 switch 디스패처. 서브커맨드 토큰 제거 후 `flag.Parse()`. → §3
- **레이어링**: 인터페이스 남발 없이 — repository=주입된 클라이언트, service=패키지 자유 함수, model+view=반환 구조체의 `String()`/`Show()`. 의존성은 **클라이언트를 첫 인자로** 주입. → §4~5
- **패키지 파일 조직**: 큰 패키지는 연산별 파일(`list.go`/`create.go`/`run.go`), 코어 타입은 `<pkg>.go`. 컬렉션은 이름 있는 슬라이스 타입 + 메서드. → §5
- **외부 API**: `Client()` 팩토리, `(result, *http.Response, error)` 관례, 동적 필드는 체이닝 접근자. → §6
- **설정**: 단일 YAML(`~/.<app>`), 런타임 필드는 `yaml:"-"`, 패키지 싱글턴. → §7
- **에러**: `errors.Wrap`, 조기 반환, 조용히 삼키지 말 것. panic은 진입점 초기화에 한정. → §8, §12
- **테스트**: 테이블 주도 + 표준 `testing`, 실패 메시지에 입력·실제·기대값. → §9
- **언어 스타일**: Effective Go / Google Go Style — `gofmt`, MixedCaps, 이니셜리즘 대소문자 통일(`URL`/`ID`), `Get` 접두어 금지, 리시버 1~2글자, 에러 문자열 소문자·마침표 없음, `%w` 래핑, `var t []string`, 인터페이스는 소비 측 정의 등. → §12