컨벤션¶

이 섹션에서는 본 모범 사례 가이드에서 사용되는 여러 규칙을 설명합니다.

아키텍처 다이어그램¶

AWS 아키텍처 아이콘¶

아키텍처 다이어그램에는 최신 AWS 아키텍처 아이콘을 사용하세요. 아이콘은 실제로 나타내는 대상에만 사용하세요.

형식 및 도구¶

아키텍처 다이어그램은 흰색과 같은 밝은 중립 배경의 PNG 파일 형식으로 제공하세요. 모든 요소 주위에 8px의 여백을 남겨두세요. 각 다이어그램에는 향후 수정이 가능하도록 draw.io 형식의 소스 파일이 함께 제공되어야 합니다.

파일 구성¶

다음 구조를 사용하여 파일을 저장하세요:

content/
  assets/
    foundation/
      vpc-setup-diagram.png
      vpc-setup-diagram.drawio
    security/
      network-acl-flow.png
      network-acl-flow.drawio

기술 요구사항¶

파일 형식: 투명 배경의 PNG
크기: 최대 너비 1200px, 가로세로 비율 유지. 다이어그램은 700px 너비로 축소했을 때도 읽을 수 있어야 합니다.
파일 크기: 최적의 로딩을 위해 500KB 미만으로 유지
해상도: 웹 표시를 위해 72~96 DPI

라이트 및 다크 모드 호환성¶

다이어그램은 라이트 및 다크 색상 테마 모두에서 사용 가능해야 합니다. 이를 위해:

투명 배경 사용 — 흰색 배경은 사용하지 마세요. 투명 배경을 사용하면 다이어그램이 두 가지 색상 테마에 모두 적응할 수 있습니다.
투명 배경 위의 텍스트와 선에는 #7E7E7E 사용 — 검정(#000000)이나 흰색(#FFFFFF)은 사용하지 마세요. 이 회색은 라이트 배경(#FFFFFF)과 다크 배경(#1e1e1e) 모두에 대해 거의 동일한 대비를 제공합니다.
색상이 채워진 노드 내부의 텍스트(채워진 배경이 있는 경우)는 흰색이나 노드의 채우기 색상에 적합한 다른 색상을 사용할 수 있습니다 — #7E7E7E 규칙은 투명 배경 위에 직접 위치하는 요소에만 적용됩니다.

대비율 제한

#7E7E7E 회색은 라이트 및 다크 배경 모두에 대해 약 4.1:1의 대비를 달성합니다. 이는 WCAG AA 최소 기준인 4.5:1보다 약간 낮습니다. 이는 허용된 절충안입니다 — 흰색과 거의 검정에 가까운 배경 모두에 대해 4.5:1 대비를 동시에 달성할 수 있는 단일 색상은 존재하지 않습니다(해당 범위는 수학적으로 상호 배타적입니다). #7E7E7E 중간값은 중복 이미지 파일 없이 두 테마 모두에서 최상의 균형 잡힌 가독성을 제공합니다.

접근성¶

접근성을 고려하여 아키텍처 다이어그램을 작성하세요. 텍스트(또는 선)와 배경의 대비율은 최소 4.5:1이어야 합니다. 일반적으로 강하게 대비되는 배경 위의 흰색 또는 검정색이 가장 좋은 선택입니다.

접근성 예시¶

좋은 대비 조합:

흰색 배경(#FFFFFF)에 검정 텍스트(#000000) - 21:1 비율
흰색 배경에 진한 회색 텍스트(#16191F) - 12.6:1 비율

나쁜 대비 조합:

흰색 배경에 밝은 회색 텍스트(#CCCCCC) - 1.6:1 비율 ❌
흰색 배경에 노란색 텍스트 - 1.1:1 비율 ❌

가이드라인¶

단순하게 유지: 가능한 한 단순한 다이어그램을 작성하세요. 필요한 경우 여러 다이어그램으로 내용을 분할하세요. 냅킨에 스케치할 수 없다면 너무 복잡한 것입니다.
이중 인코딩 사용: 색상만을 차이의 유일한 지표로 사용하지 마세요.
대체 텍스트를 신중하게 사용: 시각적 요소에 내용을 간략히 설명하는 대체 텍스트를 포함하세요.

다이어그램 스타일링¶

다음 지침을 사용하여 다이어그램의 스타일을 AWS의 시각적 스타일 및 언어에 맞추세요. 다이어그램이 다음 요소 가이드라인을 모두 충족하나요?

배경 색상: 배경 색상으로 흰색(#FFFFFF)을 사용하세요. 배경을 투명하게 두지 마세요.
선과 화살표: 선의 최소 두께/너비는 1pt여야 합니다. 기본 연결 및 컨테이너에는 실선을 사용하세요. 보조 연결 및 컨테이너는 점선으로 표현할 수 있습니다. 화살표 포인터 스타일은 닫힌 화살표보다 열린 화살표를 사용하세요.
색상: 공식 아이콘 라이브러리에서 제공하는 색상을 수정하지 마세요 — 색상에는 의미론적 의미가 포함되어 있으므로 그대로 사용하세요(예: 특정 색상은 서비스 카테고리를 나타냄). 다이어그램에 추가 색상을 추가해야 하는 경우, 색상 값이 AWS 브랜드 색상 팔레트에 포함되어 있는지 확인하세요.
타이포그래피(폰트): 대부분의 경우 Regular 굵기를 사용하세요. 필요한 경우 Bold를 사용하여 추가 강조를 제공할 수 있습니다. Thin이나 Light는 사용하지 마세요(대부분의 다이어그램에 필요한 폰트 크기 이하에서 접근성 기준을 충족하지 못합니다). 최소 폰트 크기는 12px여야 합니다. 대부분의 아이콘/일러스트레이션 레이블에는 #16191F 또는 #000000 색상을 사용하세요. 다이어그램에서는 ^{^밑줄}^보다 이탤릭체가 선호됩니다. (화살표/선이 있는 다이어그램에서 밑줄은 불필요한 시각적 노이즈를 추가할 수 있습니다.)
레이블과 텍스트: 레이블을 아이콘과 가운데 정렬하고 아이콘 아래에 배치하세요. 설명 텍스트를 이미지에 삽입하지 마세요 — 접근성이 떨어지고 현지화도 불가능합니다. 각 설명 개체나 아이콘에는 짧은 레이블만 사용하세요. 다이어그램의 특정 부분을 설명 텍스트로 강조하고 싶다면 콜아웃을 사용하세요. 이는 접근성, 현지화 및 지역 규정 준수에 더 유리합니다.
외부 프레임: 이미지의 상하좌우에 동일하게 8px의 패딩을 적용하세요. 다이어그램에 눈에 보이는 외부 테두리를 적용하지 마세요. 테두리 그림자와 페이드 효과도 사용하지 않을 것을 권장합니다.

IP 주소 표현¶

실제 네트워크와의 충돌을 방지하고 예시가 보편적으로 작동하도록 승인된 문서화 범위를 사용하세요. 자동화된 유효성 검사가 이러한 표준을 적용합니다.

예시 IP 범위 및 주소¶

"공인" IP 주소를 문서화할 때는 IPv4 및 IPv6 주소에 대해 사용 가능한 여러 문서화 범위 중 하나를 사용하세요. IPv4 범위의 좋은 예는 192.0.2.0/24이고, IPv6 범위의 좋은 예는 2001:db8::/32입니다.

"내부 범위" 예시에는 RFC1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), RFC6598 (100.64.0.0/10), 또는 RFC6815 공간(198.19.0.0/16)을 사용하세요. 이 모든 범위는 VPC 내에서 지원됩니다.

완전한 네트워크 예시¶

다중 계층 VPC 설정:

VPC: 10.0.0.0/16
  Public subnet: 10.0.1.0/24
  Private subnet: 10.0.2.0/24
  Database subnet: 10.0.3.0/24

IPv6 주소 및 네트워크 표현¶

IPv6 주소를 표현할 때는 RFC5952를 준수하세요.

	예시
올바름	`2001:db8:0:1234::`
잘못됨	`2001:0db8:0000:1234::`
잘못됨	`2001:DB8:0:1234::`
잘못됨	`2001:0DB8:0000:1234::`

콘솔 스크린샷¶

AWS 콘솔은 자주 변경되며, 한 섹션 내 여러 스크린샷 간에 일관된 모습을 유지하면서 이미지를 업데이트하기가 어렵습니다. 또한 고객은 AWS 배포 자동화에 투자해야 하며, 콘솔은 검토, 모니터링 또는 실험 용도로만 써야 합니다. 따라서 다음을 포함한 대부분의 경우에는 스크린샷 사용을 피해야 합니다:

서비스 구성 방법
기본 AWS 작업

다음의 경우에는 신중하게 고려하세요:

콘솔에서 그래픽 출력 표시(지도, 차트 등)
콘솔에서 단일 기능이나 항목 강조 표시, 특히 위치를 설명하기 복잡한 경우

빠른 체크리스트¶

다이어그램 제출 전:

최신 AWS 아키텍처 아이콘 사용
흰색 배경의 PNG 형식
일치하는 .drawio 소스 파일 포함
텍스트 대비율 ≥ 4.5:1
폰트 크기 ≥ 12px
승인된 IP 범위 사용
파일 크기 < 500KB
설명적인 대체 텍스트 포함

생성형 AI 사용¶

텍스트 콘텐츠 제작 및 이미지나 다이어그램 생성을 위한 생성형 AI 도구(Amazon Q, Claude, ChatGPT, GitHub Copilot 또는 유사 도구 등)의 사용이 허용됩니다. AI 지원 콘텐츠는 사람이 작성한 콘텐츠와 동일한 품질 기준을 충족해야 합니다 — 프로젝트의 철학과 이 페이지의 규칙은 콘텐츠가 어떻게 생성되었는지에 관계없이 적용됩니다.

AI 생성 콘텐츠 요구사항:

사람의 검토는 필수입니다. 모든 AI 생성 텍스트와 이미지는 풀 리퀘스트를 생성하기 전에 기술적 정확성, 어조 및 프로젝트 규칙 준수 여부에 대해 사람 기여자가 검토해야 합니다. AI 출력물은 초안이지 완성된 결과물이 아닙니다.
기술적 정확성은 검토자의 책임입니다. AI 도구는 사실적으로 부정확하거나 오래되었거나 미묘하게 오해를 불러일으키는 그럴듯한 콘텐츠를 생성할 수 있습니다. 검토자는 서비스 기능, 요금 세부 정보, API 동작 및 아키텍처 권장 사항을 현재 AWS 문서와 대조하여 확인해야 합니다.
콘텐츠 자체에 AI 사용 여부를 공개하지 마세요. 독자는 콘텐츠가 사람이 작성했는지 AI의 도움을 받았는지 알 수 없어야 합니다. 품질 기준은 어느 경우에나 동일합니다.
AI 도구를 위한 스티어링 규칙이 존재합니다. 이 프로젝트에는 저장소에서 작업하는 AI 도구에 구조 및 형식 지침을 제공하는 .kiro/steering/content-conventions.md 파일이 포함되어 있습니다. AI 도구를 사용하는 기여자는 일관된 출력을 위해 해당 도구가 이 파일을 인식하도록 해야 합니다.
AI가 생성한 이미지도 동일한 기준을 충족해야 합니다. AI 생성 다이어그램은 승인된 AWS 아키텍처 아이콘을 사용하고, 접근성 대비 요구사항을 충족하며, 향후 편집을 위한 .drawio 소스 파일을 포함해야 합니다 — 사람이 만든 다이어그램과 동일한 기준입니다.

요금 참조¶

네트워킹 서비스 및 아키텍처 결정의 비용 영향을 논의할 때:

구체적인 달러 금액이 아닌 요금 차원을 참조하세요. AWS 요금은 리전마다 다르며 자주 변경됩니다. 구체적인 가격(예: "$0.045/GB")을 포함하지 말고, 무엇에 대해 요금이 부과되는지(시간당, GB당 처리, 연결당, 요청당)와 서비스 간 상대적 비교를 설명하세요.
상대적 비교를 사용하세요. "VPC 피어링은 데이터 처리 요금이 없는 반면 Transit Gateway는 GB당 요금이 부과됩니다" 또는 "DNS Firewall은 동일한 트래픽 볼륨에 대해 Network Firewall보다 훨씬 저렴합니다"와 같은 표현은 리전과 시간에 관계없이 지속적으로 정확합니다.
공식 요금 페이지로 링크하세요. 비용이 결정 요소인 경우, 독자가 해당 리전의 현재 값을 조회할 수 있도록 관련 AWS 요금 페이지 링크를 포함하세요.