`tol-`, `inf-` (공용 도구/인프라) Repository README 작성 가이드

tol-* (tool) 또는 inf-* (infrastructure) 접두사를 사용하는 저장소는 여러 프로젝트에서 공통으로 사용되는 도구나 인프라 구성(IaC) 코드를 관리합니다. README의 핵심 목표는 사용자가 이 도구를 '어떻게' 사용하는지, 인프라를 '어떻게' 배포하고 관리하는지에 대한 명확하고 실용적인 가이드를 제공하는 것입니다.

1. 도구/인프라 개요 (Overview)

목적 (Purpose): 이 도구가 해결하는 문제나, 이 인프라 코드가 구성하는 시스템이 무엇인지 명확하게 설명합니다.
- 예시 (tol-): "이 CLI 도구는 여러 Git 저장소에 분산된 package.json의 의존성 버전을 한 번에 동기화합니다."
- 예시 (inf-): "이 Terraform 코드는 AWS EKS 클러스터와 네트워킹, IAM 역할을 표준 구성으로 배포합니다."
아키텍처 (Architecture):
- 도구의 경우, 주요 기능과 동작 방식을 설명하는 간단한 다이어그램을 포함하면 좋습니다.
- 인프라의 경우, 프로비저닝될 클라우드 리소스의 관계를 보여주는 아키텍처 다이어그램(예: Mermaid.js, Cloudcraft)을 반드시 포함해야 합니다.

2. 설치 및 설정 (Installation and Setup)

설치 방법 (Installation):
- CLI 도구: pip, npm, go install 등을 이용한 설치 방법을 안내하거나, 바이너리 파일을 다운로드하는 방법을 설명합니다.
```
npm install -g @my-org/dependency-sync-tool
```
- 인프라 코드 (IaC): Terraform, Ansible 등 필요한 도구의 설치 및 버전 요구사항을 명시합니다.
```
# Terraform 1.2.x 이상 버전 필요
brew install terraform
```
초기 설정 (Configuration):
- 인증 (Authentication): AWS 자격 증명, GitHub 토큰 등 도구/인프라 사용에 필요한 인증 정보를 어떻게 설정하는지 안내합니다.
- 환경 변수: .env.example 파일을 제공하고, 각 변수의 의미와 설정 방법을 설명합니다.
- 인프라 변수: Terraform의 terraform.tfvars.example 파일을 제공하여 사용자가 자신의 환경에 맞게 수정할 수 있도록 안내합니다.

3. 사용법 (Usage)

가장 중요한 섹션: 사용자가 실제로 도구를 사용하거나 인프라를 배포하는 구체적인 예시를 제공합니다.

CLI 도구 사용 예시:

자주 사용되는 명령어와 옵션을 실제 예시와 함께 보여줍니다.

# 현재 디렉토리 하위의 모든 package.json에서 'react' 버전을 18.2.0으로 통일
dep-sync --lib react --version 18.2.0

# 미리보기 모드로 실행 (실제 파일은 변경하지 않음)
dep-sync --lib react --version 18.2.0 --dry-run

인프라 배포 스크립트 예시:

개발, 스테이징, 프로덕션 환경별로 인프라를 배포하는 명령어를 명확히 구분하여 제공합니다.

# 1. 개발 환경 초기화 (dev.backend.tfvars 사용)
terraform init -backend-config=dev.backend.tfvars

# 2. 배포 계획 확인
terraform plan -var-file=dev.tfvars

# 3. 개발 환경에 배포
terraform apply -var-file=dev.tfvars

4. 권한 및 정책 (Permissions and Policies)

목적: 이 도구나 인프라를 사용하기 위해 필요한 IAM 권한이나 접근 정책을 명시합니다.
팁: 최소 권한 원칙(Principle of Least Privilege)에 따라 필요한 권한 목록(JSON 형식)을 제공하면 사용자가 IAM 정책을 쉽게 생성할 수 있습니다.

5. 유지보수 및 트러블슈팅 (Maintenance and Troubleshooting)

업데이트 방법: 도구의 버전을 업그레이드하거나, 인프라 변경 사항을 적용하는 방법을 안내합니다.
자주 묻는 질문 (FAQ): 사용 중 발생할 수 있는 흔한 문제와 해결 방법을 정리합니다.
- "Q: AccessDenied 오류가 발생합니다. -> A: AWS 자격 증명에 s3:PutObject 권한이 있는지 확인하세요."

4.1 KiB Raw Permalink Blame History

tol-*, inf-* (공용 도구/인프라) Repository README 작성 가이드