다중 언어 코드형 인프라(IaC) 라이브러리에 기존 사용자를 깨지 않고 기능 추가하기

## 기존 사용자 코드를 깨지 않고 플랫폼 기능 모두 쓸 수 있게 하기 변경을 요청한 사람만이 아니라 라이브러리의 사용자, 유지 관리자, 더 넓은 생태계를 위해 작업하세요. - 하위 호환성을 유지하세요. 기존 사용자 코드와 합성된 인프라는 기본적으로 계속 작동해야 합니다. - 최소 놀람 원칙을 따르세요. API는 사용자의 사고방식과 일치해야 합니다. - 합리적이고 재정의할 수 있는 기본값을 제공하면서 플랫폼의 전체 기능 범위를 노출하세요. - 상위 수준 기능이 없어도 사용자가 막히지 않도록 생성된 하위 수준 리소스로 접근할 수 있는 우회 수단을 유지하세요. - 규칙이 모호하면 조용히 추측하지 말고 변경 설명에 결정과 근거를 기록하세요. 요청된 작업이 이러한 종류의 라이브러리에 대한 코드 작성 또는 검토 범위를 벗어나면 중단하고 범위 불일치를 알리세요. 관련 없는 작업에 특수 규칙을 적용하지 마세요. ## 대부분의 기능은 직접 작성한 Level 2 API에 두기 서로 구분되는 세 가지 추상화 수준을 유지하세요. - 수준 1은 공급자의 리소스 스키마를 감싸는 생성된 래퍼로 구성됩니다. 절대 수동으로 편집하지 마세요. - 수준 2는 유용한 기본값을 갖춘 수동 작성 의도 기반 API로 구성됩니다. 대부분의 기능 작업은 여기에 속합니다. - 수준 3은 여러 리소스를 아우르는 패턴으로 구성됩니다. 저장소가 해당 추상화 수준을 명시적으로 허용할 때만 새 패턴을 추가하세요. 수준 2는 공급자의 원시 스키마가 아니라 사용자의 의도를 중심으로 설계하세요. 일반 호출자에게는 생성된 스키마 세부 정보, 내부 연결, 권한 작업, 물리적 식별자를 숨기되 공급자의 전체 기능 집합은 계속 노출하세요. 타사 구현이 기본 제공 구현처럼 작동할 수 있도록 리소스 계약을 인터페이스로 표현하세요. 매개변수를 충족하는 가장 작은 인터페이스를 선호하세요. 먼저 식별자 전용 참조를 사용하고, 편의 작업이 필요한 경우에만 전체 동작 인터페이스를 사용하며, 구체 클래스는 예외적인 경우에만 사용하세요. ## 새 기능마다 mixin, facade, trait 중 어디에 둘지 정하기 각 기능이 영향을 미치는 대상에 따라 배치하세요. 1. 논리 없이 하위 수준 속성을 직접 전달하는 기능은 간단한 속성 믹스인에 속합니다. 2. 리소스 자체의 속성이나 수명 주기를 변경하는 논리는 독립형 믹스인에 속합니다. 3. 권한 부여, 지표, 이벤트처럼 외부 소비자에게 제공되는 동작은 퍼사드에 속합니다. 4. 다른 구문이 조회하는 횡단 기능은 트레이트에 속합니다. 5. 그 외에는 수준 2 구문의 메서드를 사용하세요. 이 역할들을 혼동하지 마세요. 믹스인은 내부를 향하고, 퍼사드는 외부를 향하며, 트레이트는 서비스에 독립적인 기능을 나타냅니다. 객체가 패키지 또는 언어 경계를 넘을 수 있으므로 `instanceof` 대신 안정적인 런타임 마커를 기반으로 한 정적 형식 가드를 사용하세요. 구현을 위해 추상 기반 클래스를 제공하되 공개 매개변수로 받지는 마세요. ## 공개 이름을 일관되게 짓고 다른 언어에서 못 쓰는 타입 피하기 일관된 공개 이름을 사용하세요. 클래스와 열거형에는 PascalCase, 속성과 메서드에는 camelCase, 동작 인터페이스에는 `I` 접두사, 데이터 구조에는 접두사 없음, 열거형 멤버에는 대문자 스네이크 표기법을 사용하세요. 공식 플랫폼 용어를 유지하고 강한 형식을 사용할 수 없으면 단위를 포함하세요. 속성 객체는 읽기 전용이고 평면적이어야 하며 구문의 이름을 따라야 합니다. 모든 선택적 속성에는 단순히 정의되지 않았다고 적는 대신 동작을 설명하는 기본값이 문서화되어야 합니다. 원시 숫자나 식별자 문자열보다 기간, 크기, 리소스 참조에 대한 강한 형식을 선호하세요. 상위 수준 속성을 통해 생성된 하위 수준 형식을 노출하지 마세요. 바인딩 생성기가 지원하지 않는 유니온 형식과 기타 구문을 피하고, 대신 열거형과 유사한 클래스, 별도의 속성 객체 또는 팩터리 메서드를 사용하세요. 공개 형식 파일의 위치는 외부 계약의 일부입니다. 함부로 이동하지 마세요. 대상 언어에서 일관되게 표현할 수 없다면 매핑 형식이나 조건부 형식, 오버로드된 함수, 언어별 네임스페이스, 내보낸 객체 상수를 피하세요. `this`를 반환하는 플루언트 메서드를 사용하지 마세요. 언어 간 변환이 원활하지 않고 체이닝 뒤에 변경을 숨깁니다. ## 명확한 검증 오류를 내고 미해결 값을 먼저 확인하기 구문 컨텍스트가 있으면 범위가 지정된 검증 오류를 사용하고, 그렇지 않으면 범위가 없는 검증 오류를 사용하세요. 오류 코드는 컴파일 시점 리터럴이어야 하고 원인과 해결 방법이 같으면 재사용할 수 있어야 하며, 메시지에는 잘못된 값, 예상 값, 필요한 수정 사항이 명시되어야 합니다. 오류를 발생시키기보다 안전한 구성을 자동으로 수정하는 방식을 선호하세요. API 오용은 조기에 실패시키고, 누적 상태에는 생성 후 검증을 연결하며, 환경 문제에는 합성 진단을 내보내세요. 복구할 수 없는 생성 오류를 잡지 말고, 실제로 복구 가능한 결과는 반환 값으로 표현하세요. 미해결 값은 문자열, 숫자, 목록 또는 리소스 속성을 나타낼 수 있습니다. 길이, 범위, 반복 또는 참·거짓 여부를 검증하기 전에 값이 미해결인지 확인하세요. 토큰화된 목록은 마커 길이를 노출할 수 있고 토큰화된 스칼라 값은 거짓으로 보일 수 있습니다. 선택적 값에는 명시적인 undefined 검사를 사용하고, 토큰을 인식하는 숫자 변환을 사용하며, 물리적 이름의 해시에 미해결 리소스 속성을 절대 포함하지 마세요. 생성 후 누적되는 상태에는 변경 호출 위치를 캡처하는 지연 값 상자를 사용하세요. 목록, 값, 맵 또는 집합 상자를 사용하고, 토큰 어댑터를 통해 하위 수준 속성에 전달하고, 상자 작업으로 변경하며, 지연 콜백이나 상자 콜백 안에서는 구문 트리를 절대 변경하지 마세요. ## 권한을 좁게 유지하고 동작 변경은 기능 플래그로 보호하기 전체 서비스 와일드카드보다 구체적인 권한 작업을 선호하고, 리소스 식별자를 가능한 한 가장 좁은 접두사로 제한하며, 관련 작업을 리소스 범위별로 그룹화하세요. 정책 문을 직접 조립하지 말고 라이브러리의 권한 부여 도우미를 사용하세요. 혼동된 대리자 위험이 있는 경우 신뢰 정책에 소스 계정과 소스 리소스 조건을 포함해야 합니다. 암호화 권한은 의도한 서비스를 통해서만 사용하도록 제한해야 합니다. 구성이 공개 액세스를 생성할 때마다 합성 시점 경고를 내보내세요. 기존 API의 관찰 가능한 동작이 변경되면 기능 플래그로 호환성을 보호하세요. - 이전 동작이 잘못된 경우 버그 수정 플래그를 사용하세요. - 이전 동작이 여전히 유효하지만 더 이상 권장되지 않는 경우 API 기본값 플래그를 사용하고 이전 동작과의 호환성을 문서화하세요. - 구성하지 않은 애플리케이션은 이전 동작을 유지해야 합니다. - 보안 플래그는 신뢰나 권한을 줄일 수 있지만 조용히 넓혀서는 안 됩니다. 더 넓은 액세스에는 명시적인 API 옵션이 필요합니다. 대체 구문이 있다는 이유만으로 플래그를 사용하지 마세요. 대신 기존 구문을 사용 중단 처리하고 표준 주석 메커니즘을 통해 동작 변경을 경고하세요. ## 영향받는 패키지를 먼저 빌드하고 통합 스냅숏 업데이트하기 테스트, 린트, 통합 스냅샷 또는 문서 예제 검사를 실행하기 전에 영향을 받는 패키지를 빌드하세요. 반복 작업 중에는 관련 범위가 가장 좁은 모듈이나 테스트 대상을 사용하고, 인계 전에는 저장소에서 요구하는 패키지 및 호환성 게이트로 돌아가세요. 생성되는 파일, 안정 및 실험용 통합 테스트의 위치, 그리고 사람을 위한 긴 가이드보다 우선하는 에이전트용 설계 참조의 위치를 파악하세요. 생성된 수준 1 소스를 직접 편집하지 마세요. 대체 빌드 경로를 임의로 만들지 말고 저장소 로컬 패키지 명령과 작업 디렉터리를 사용하세요. 자동 린트 수정으로 생기는 차이가 요청된 범위 안에 있을 때만 이를 실행하세요. 논리 식별자를 변경할 때는 패키지 간 스냅샷을 포함해 영향을 받는 모든 통합 스냅샷을 업데이트하세요. 로컬 단위 테스트가 성공했다고 해서 생성된 바인딩, 문서 예제 또는 통합 템플릿이 여전히 컴파일된다는 증거는 아닙니다. ## 새 공개 API를 모두 문서화하고 예제가 컴파일되게 유지하기 새로운 모든 공개 클래스, 메서드, 속성, 인터페이스를 문서화하세요. 간결한 요약을 작성한 다음 빈 줄과 설명 본문을 추가하세요. 해당되는 경우 매개변수, 반환, 기본값, 관련 참조, 예제, 생성된 속성 태그를 포함하세요. 속성 이름은 모호한 이름 대신 리소스 형식으로 시작해야 합니다. 가능한 경우 권위 있는 플랫폼 설명을 복사하되, 기본 인터페이스에서 문서를 상속하는 재정의에는 문서를 중복하지 마세요. 각 모듈 가이드는 성숙도를 명시하고, 상단 가까이에 간단한 예제를 배치하며, 주요 사용 사례의 예제를 포함해야 합니다. 일반적인 형식 지정 예제는 모두 컴파일되어야 합니다. 픽스처를 실제로 적용할 수 없는 경우에만 저장소의 명시적 제외 마커를 사용하세요. 모든 기능 변경은 관련 모듈 가이드를 업데이트해야 합니다. 문서 전용 텍스트는 API 테스트를 대체할 수 없고, API 구현은 오래된 예제를 방치할 이유가 되지 않습니다. ## 단위 테스트에서 중요한 속성을 확인하고 통합 테스트 추가하기 단위 테스트에서는 전체 템플릿을 비교하거나 임의의 값을 허용하는 대신 중요한 특정 생성 속성을 검증하세요. 부분 객체, 정확한 객체, 배열, 정규식, 부재 매처를 의도에 맞게 사용하세요. 데이터 기반 테스트로 경계값을 다루세요. 오류 테스트는 정확한 진단을 검증해야 하며 테스트 이름에 실패 동작을 명시해야 합니다. 유틸리티 함수는 구문과 별도로 테스트하고 사용 중단된 API의 테스트를 유지하세요. 새로운 선택적 속성에는 기본 동작이 변경되지 않았음을 입증하는 하위 호환성 테스트가 필요합니다. 권한 부여 도우미는 생성된 역할과 가져온 역할, 사용자, 서비스 주체로 테스트해야 합니다. 통합 테스트는 별도의 추가 합성 호출 없이 저장소의 통합 테스트 구문을 사용해야 합니다. 모든 새 테스트에는 어설션이 권장되며 사용자 지정 리소스에는 필수입니다. 공개 액세스가 테스트 대상 동작인 경우를 제외하고 개방형 네트워크 피어를 피하세요. 새로 생성된 리소스 형식 또는 속성, 서비스 간 동작, 새 버전, 사용자 지정 리소스에 대한 통합 범위를 추가하세요. 기능 영역별로 테스트를 분리하고 스냅샷 확장자와 위치를 일관되게 유지하세요. ## 이슈와 연결한 변경 제목을 쓰고 고정 식별자는 절대 바꾸지 않기 해당하는 경우 영향을 받는 모듈을 포함한 일반적인 변경 제목을 사용하세요. 기능 및 수정 변경은 이슈를 참조해야 합니다. 기능 변경에는 단위 테스트, 통합 스냅샷, 모듈 문서 업데이트가 필요합니다. 호환성을 깨는 변경은 명시적으로 실험용인 패키지에서만 허용되며 변경 설명에 눈에 띄게 선언해야 합니다. 변경 하나에는 하나의 관심사만 담고, 외관상 수정은 별도로 제출하세요. 추측성 추상화를 추가하거나, 안정적인 구문 식별자를 변경하거나, 주석 처리되거나 사용되지 않는 코드를 남기거나, 위반을 숨기기 위해 린트 규칙을 무시하지 마세요. 식별자 변경은 배포된 리소스를 교체하고 데이터 손실을 일으킬 수 있습니다. 기존 API에 검증을 추가하기 전에 이전에 허용된 입력이 성공적으로 배포될 수 있었는지 확인하세요. 가능했다면 새로운 거부 동작을 호환성 플래그로 보호하세요. 배포 시 항상 실패했다면 조기 합성 실패를 선호하고 더 엄격한 검증이 정당한 이유를 문서화하세요. 인계 전에 생성된 파일 편집, 공개 형식 이동, 바인딩과 호환되지 않는 구문, 오래된 스냅샷, 누락된 문서, 호환성 회귀, 관련 없는 변경이 있는지 차이를 검토하세요.