도입

`sample-ai-coding-standards-template`는 AWS Samples 공식 GitHub에 올라온 AI 기반 개발용 프로젝트 템플릿입니다. AI 코딩 어시스턴트가 팀의 코딩 규칙, 아키텍처 기준, 보안 기준을 잘 모른 채 제각각 코드를 만드는 문제를 줄이기 위해 사용합니다.

특히 서버리스 풀스택 애플리케이션을 팀 단위로 만들 때, 처음부터 보안·테스트·문서화·CI/CD 기준을 함께 잡고 싶은 경우에 적합합니다.

왜 좋은가 / 왜 유명한가

- AWS Samples 공식 저장소에 공개된 자료입니다. 개인이 만든 예제가 아니라 AWS 샘플 프로젝트로 배포되어 팀 내 도입 검토 시 신뢰도를 확보하기 좋습니다.

- AI 코딩 어시스턴트가 참고할 프로젝트별 규칙과 패턴을 제공하는 데 초점이 있습니다. README에서는 AI 어시스턴트가 프로젝트 맥락과 표준을 모르기 때문에 일관성 없는 코드를 만들 수 있다는 문제를 직접 다룹니다.

- AWS Well-Architected 모범 사례를 반영한 엔터프라이즈급 템플릿을 지향합니다. 보안, 품질 검사, 테스트, 문서화, CI/CD까지 개발 표준을 넓게 다룹니다.

- 헥사고날 아키텍처를 기반으로 합니다. 비즈니스 로직과 AWS 서비스 같은 외부 인프라를 분리해 테스트와 유지보수를 쉽게 만드는 구조입니다.

- 팀 단위 AI 코딩 표준화에 맞춰져 있습니다. 단순 샘플 앱이 아니라 개발 규칙, AI 어시스턴트 설정, 보안 훅, 품질 게이트를 함께 제공하는 형태입니다.

무엇을 할 수 있나 / 무엇이 들어있나

이 템플릿의 핵심은 “AI가 코드를 더 잘 만들도록 프로젝트 기준을 미리 제공하는 것”입니다. README에서 확인되는 주요 구성은 다음과 같습니다.

- 표준화된 개발 규칙과 패턴

AI 코딩 어시스턴트가 프로젝트의 코드 스타일, 구조, 개발 방식을 일관되게 따르도록 기준을 제공합니다.

- 사전 구성된 AI 어시스턴트 설정

프로젝트 컨텍스트를 AI 도구가 참고할 수 있게 구성하는 방향의 템플릿입니다. 검색 요약 기준으로는 `rules/aws.md`, `mcp/mcp.json`, `hooks/architecture-decision-record.hook` 같은 규칙·MCP·훅 관련 파일이 포함된 것으로 알려져 있습니다.

rules/aws.md
mcp/mcp.json
hooks/architecture-decision-record.hook

- 프로덕션 준비형 아키텍처 패턴

README에서는 “production-ready architecture patterns”를 제공한다고 설명합니다. 단순 예제 수준이 아니라 실제 운영 환경을 고려한 구조를 목표로 합니다.

- 자동 보안·품질 검사와 테스트

보안 스캔, 코드 품질 게이트, 자격 증명 스캔, 의존성 취약점 검사, 설정 검증을 언급합니다. 팀원마다 동일한 기준을 적용하기 위한 pre-commit 보안 훅도 포함된다고 설명합니다.

- AWS 보안 모범 사례

README에서 확인되는 보안 관련 예시는 다음과 같습니다.

- DynamoDB 테이블을 AWS 관리형 키로 암호화

- AWS Cognito와 JWT 토큰 검증

- CloudFront의 HTTPS 강제 적용

- ACM 인증서 사용

- AWS Security Helper를 통한 자동 보안 스캔

- pre-commit 보안 훅을 통한 품질 게이트 적용

- 헥사고날 아키텍처

도메인 코드를 AWS 서비스와 분리합니다. DynamoDB, S3, API 같은 외부 연동은 어댑터가 담당하고, 비즈니스 로직은 순수하게 유지하는 방식입니다.

- 재사용 가능한 CDK Construct

README에서 언급된 Construct 예시는 다음과 같습니다.

- `CognitoAuth`: 네이티브 인증과 페더레이션 인증 처리

- `StaticWebsite`: S3, CloudFront, Route 53, ACM, WAF 기반 정적 웹사이트 배포

- 재사용 가능한 React 컴포넌트

인증 모듈과 UI 컴포넌트 구성을 제공합니다.

- `AuthProvider`

- `useAuth` hook

- 이메일/비밀번호 인증

- OIDC federation

- Material Design 3 컴포넌트

- 다크 모드

- 접근성

- 반응형 디자인

- 환경별 설정 관리

Development, Staging, Production 환경을 고려한 설정 관리를 제공합니다. README에서는 `AppConfig` CDK Construct를 통해 우선순위 계층 기반의 환경별 설정 해석을 제공한다고 설명합니다.

- 실제 AWS 서비스를 사용하는 통합 테스트

README 기준으로 모든 테스트가 mock 없이 실제 AWS 서비스를 사용한다고 되어 있습니다.

- Backend 테스트: 실제 DynamoDB 작업과 Lambda 호출 검증

- Frontend E2E 테스트: 실제 Cognito 인증 및 배포된 API와 상호작용

- GitLab 기반 CI/CD

다중 환경 GitLab pipeline을 제공합니다.

- Development: feature branch

- Staging: main branch

- Production: Git tag

- 환경별 AWS 계정과 리전 지원

- 자동 보안 스캔

- 통합 테스트

- 배포 게이트

- 문서화

MkDocs 기반 API 문서 자동 생성과 ADR, 즉 Architecture Decision Records를 통한 아키텍처 의사결정 기록을 포함합니다.

설치와 사용법

공식 README에는 `Quick Start` 섹션이 있으나, 제공된 원문 발췌에는 실제 설치 명령이 생략되어 있습니다. 따라서 아래 글에서는 명령을 임의로 만들지 않고, 확인된 저장소와 파일 구조 중심으로 시작 방법을 안내합니다.

자료 위치는 다음 GitHub 저장소입니다.

https://github.com/aws-samples/sample-ai-coding-standards-template

공식 README에서 설치 명령과 초기화 명령을 확인한 뒤 그대로 실행해야 합니다. 제공된 원문에서 확인되는 Quick Start 코드 블록은 다음처럼 시작하지만, 실제 명령 부분은 발췌에 포함되어 있지 않습니다.

# In

실제로 사용할 때는 다음 순서로 접근하면 됩니다.

1. GitHub 저장소에 접속합니다.

https://github.com/aws-samples/sample-ai-coding-standards-template

2. README의 `How to Use the Solution`과 `Quick Start` 섹션을 확인합니다. 설치, 초기화, 배포 관련 명령은 해당 섹션의 최신 내용을 기준으로 실행해야 합니다.

3. 팀 프로젝트에 적용할 때는 먼저 AI 어시스턴트가 참고할 규칙 파일과 훅 설정을 확인합니다.

rules/aws.md
mcp/mcp.json
hooks/architecture-decision-record.hook

4. 팀의 개발 기준과 맞는지 검토합니다. 예를 들어 다음 항목을 먼저 확인하는 방식이 좋습니다.

- 우리 팀의 AWS 계정 구조와 환경 구분이 Development / Staging / Production과 맞는가
- GitLab pipeline을 사용하는 조직인가
- Cognito, DynamoDB, S3, CloudFront, Route 53, ACM, WAF 구성이 필요한 프로젝트인가
- AI 코딩 어시스턴트가 따라야 할 규칙을 현재 팀 표준에 맞게 조정할 필요가 있는가

5. AI 코딩 어시스턴트와 함께 사용할 때는 “새 기능을 만들어 달라”는 요청만 하기보다, 템플릿의 규칙과 아키텍처를 지키도록 작업 지시를 구체화합니다.

예시 지시문은 다음처럼 작성할 수 있습니다.

이 프로젝트의 헥사고날 아키텍처 구조를 유지하면서 기능을 추가해 주세요.
비즈니스 로직은 도메인 계층에 두고, DynamoDB 접근은 어댑터 계층에서 처리해 주세요.
기존 보안 및 테스트 규칙을 따르고, 필요한 경우 ADR에 의사결정을 기록해 주세요.

또 다른 예시는 인증 기능을 다룰 때입니다.

기존 CognitoAuth 구성과 AuthProvider, useAuth 패턴을 따르세요.
이메일/비밀번호 인증과 OIDC federation 흐름을 깨지 않도록 변경 범위를 최소화해 주세요.
프론트엔드 변경 시 접근성, 반응형 디자인, 다크 모드 기준을 유지해 주세요.

이 템플릿은 “처음부터 빈 프로젝트를 만드는 용도”라기보다, AI 어시스턴트가 따라야 할 개발 기준을 프로젝트 안에 심어두고 팀 전체의 결과물을 일정하게 만드는 용도에 가깝습니다.

주의할 점

- 실제 AWS 리소스를 사용하는 테스트가 포함됩니다. README 기준으로 backend 테스트는 실제 DynamoDB와 Lambda, frontend E2E 테스트는 실제 Cognito와 배포된 API를 사용합니다. 테스트만 실행해도 AWS 리소스 비용이나 권한 문제가 생길 수 있으므로 계정, 리전, 권한, 비용 정책을 먼저 확인해야 합니다.

- GitLab CI/CD를 전제로 한 구성이 포함됩니다. GitHub Actions나 다른 CI 도구를 쓰는 팀은 그대로 붙이기보다 파이프라인 구조를 변환해야 할 수 있습니다.

- 보안 훅과 품질 게이트가 강하게 적용될 수 있습니다. 자격 증명 스캔, 의존성 취약점 검사, 설정 검증이 포함되어 있으므로 기존 코드베이스에 바로 적용하면 초기에 많은 수정이 필요할 수 있습니다. 대신 팀 표준을 엄격히 맞추는 데는 유리합니다.

출처와 다운로드

공식 저장소는 아래에서 확인할 수 있습니다.

https://github.com/aws-samples/sample-ai-coding-standards-template

커뮤니티 게시글 하단 첨부파일로도 받을 수 있습니다. 첨부본을 사용할 때도 최신 설치 명령과 설정 변경 사항은 위 GitHub README를 함께 확인하는 편이 안전합니다.