기록 기반 재구성 프로젝트 가이드

목적

• 이 저장소는 "기억"이 아닌 "기록"을 기반으로 시스템을 재구성하는 운영 원칙을 담습니다.
• 사람과 AI가 동일한 기준으로 환경/설정/배포를 재현하는 것을 목표로 합니다.

핵심 원칙

• 선언형(Declarative): 원하는 상태를 코드/설정으로 명시
• 버전관리(Versioned): 모든 변경은 Git 이력으로 추적
• 재현가능(Reproducible): 동일한 저장소 상태로 환경 재구성 가능
• 자동화(Automatable): 반복 작업은 스크립트/CI로 실행
• 비밀분리(Secret Separation): 민감정보는 코드와 분리

문서 구조

• /Users/llsg822/dev/demo/README.md: 프로젝트 진입점
• /Users/llsg822/dev/demo/RECORDED_CONFIGURATION_GUIDE.md: 상세 운영 원칙 및 선택지
• /Users/llsg822/dev/demo/docs/PREREQUISITES.md: 환경 재현을 위한 필수 도구/버전

사용 방법

1. 새 변경을 시작하기 전에 RECORDED_CONFIGURATION_GUIDE.md 확인
2. TBD 항목이 있으면 먼저 도구/방식 결정
3. 구현 후 문서와 CI 규칙을 함께 업데이트

초기 템플릿 구조

• /Users/llsg822/dev/demo/apps/backend: Kotlin Spring Boot + Flyway + OpenAPI-first
• /Users/llsg822/dev/demo/apps/frontend: React + TypeScript + pnpm + Playwright
• /Users/llsg822/dev/demo/infra/terraform: Terraform baseline
• /Users/llsg822/dev/demo/infra/helm/demo-app: Helm chart skeleton
• /Users/llsg822/dev/demo/infra/gitops/apps: Argo CD application manifests
• /Users/llsg822/dev/demo/secrets: SOPS encrypted secret templates
• /Users/llsg822/dev/demo/.github/workflows/ci.yml: CI template

빠른 시작

1. 필수 도구 확인

cd /Users/llsg822/dev/demo
./scripts/verify-prerequisites.sh

2. 프론트 의존성 설치

./scripts/bootstrap.sh

3. 백엔드 로컬 실행

cd apps/backend
docker compose up -d
gradle bootRun

4. 프론트 로컬 실행

cd apps/frontend
pnpm dev

지금 결정할 항목 (Owner Decision)

아래는 현재 최종 결정된 항목입니다.

Domain	Decision Item	Options	Selected
Backend	Build system	Gradle Kotlin DSL / Maven	Gradle Kotlin DSL
Backend	DB migration tool	Flyway / Liquibase	Flyway
Backend	API contract style	OpenAPI-first / Code-first	OpenAPI-first
Infra	IaC tool	Terraform / Pulumi	Terraform
Infra	K8s packaging	Helm / Kustomize	Helm
Infra	GitOps controller	Argo CD / Flux	Argo CD
Frontend	Package manager	pnpm / npm	pnpm
Frontend	E2E test tool	Playwright / Cypress	Playwright
Security	Secret management	AWS Secrets Manager / Vault / SOPS	SOPS
Delivery	CI platform	GitHub Actions / GitLab CI / Jenkins	GitHub Actions
Delivery	Deploy strategy	GitOps pull / Pipeline push	GitOps pull

벤더 종속 최소화 원칙

• 비밀관리: 클라우드 전용 서비스 대신 SOPS를 기본 사용
• 배포/운영: 특정 벤더 기능보다 Kubernetes + Helm + Argo CD 표준 워크플로우 우선
• CI: GitHub Actions를 사용하되, 실제 빌드/테스트 로직은 스크립트화해 이식 가능하게 유지

결정 반영 규칙

• 선택 완료 시 아래 2개 파일을 같이 업데이트합니다.
  • /Users/llsg822/dev/demo/README.md 의 Selected 컬럼
  • /Users/llsg822/dev/demo/RECORDED_CONFIGURATION_GUIDE.md 의 Current Status/Owner Decision

다음 단계

• /Users/llsg822/dev/demo/docs/PREREQUISITES.md 기준으로 로컬/CI 환경을 먼저 맞춘 뒤, 초기 프로젝트 템플릿을 생성합니다.