다중 프로토콜 통합 게이트웨이를 권한 검사를 깨지 않고 수정·검토하기

## 가장 가까운 지침을 찾고, 정보가 다르면 실행 중인 코드를 따르기 저장소 전체 지침부터 확인한 다음, 변경할 파일과 가장 가까운 분야별 지침을 찾으세요. 테스트, 플러그인, 배포 차트, 문서, 프로토콜 서버, 성능에 민감한 런타임은 서로 다른 작업 흐름을 사용할 수 있습니다. 근거 없이 한 분야의 규칙을 다른 분야에 적용하지 마세요. 코드 기여자용 지침과 최종 사용자용 런타임 지침을 구분하세요. 배포된 시스템을 사용하는 모델이나 클라이언트를 위해 작성된 자료가 코드베이스를 수정하는 에이전트를 자동으로 통제하지는 않습니다. 편집하기 전에 시스템을 파악하세요. - 애플리케이션 진입점과 환경 설정. - 검증 스키마, 영속성 모델, 마이그레이션. - 비즈니스 서비스, 라우트, 미들웨어, 프로토콜 전송 방식. - 인증, 권한 부여, 플러그인, 연합 경계. - 테스트, 문서, 배포 자산, 관리 인터페이스. 출처가 서로 다르면 실제로 실행되는 코드와 정식 설정을 가장 먼저 따르고, 그다음 지원되는 빌드 대상과 의존성, 환경 예시, 마지막으로 문서나 주석을 따르세요. 오래될 수 있는 수량이나 운영 한계를 다시 언급하기 전에 현재 구현을 확인하세요. 활성 소스 경로를 먼저 확인하세요. 요청이 명시적으로 포함하지 않았다면 임시 작업 공간, 로그, 커버리지 결과, 생성된 산출물, 보류된 작업 폴더는 무시하세요. ## 변경할 때마다 프로젝트 검사와 비밀 정보 탐지를 통과시키기 하위 도구를 임의 옵션으로 직접 호출하지 말고 저장소가 지원하는 작업 실행기와 버전이 고정된 툴체인을 사용하세요. 개발 환경을 정식 예시와 대조해 검증하고, 필요한 준비 또는 인터페이스 생성 단계를 실행하며, 작업에 맞는 로컬 서버나 테스트 모드를 선택하세요. 코드를 변경한 후에는 다음을 수행하세요. 1. 변경한 언어와 파일을 직접 다루는 형식, lint, 타입, 보안, 문서 검사를 실행하세요. 2. 반복 작업 중에는 범위를 좁힌 검사를 사용하고, 완료를 제안하기 전에 저장소가 요구하는 종합 품질 관문을 실행하세요. 3. 보조 시스템 언어나 고성능 런타임의 경우 형식 검사, 경고를 오류로 처리하는 linter, crate 또는 패키지 테스트를 실행하세요. 4. 생성형 관리 자산이나 클라이언트 자산의 소스가 바뀌면 해당 자산을 다시 빌드하세요. 5. 외부에서 확인할 수 있는 모든 변경에 동작 테스트를 포함하세요. 비밀 정보 탐지를 품질 관문으로 사용하세요. 오탐으로 확인된 경우 테스트나 예시의 동작을 바꿀 수 없는 위치에서만 프로젝트가 허용한 인라인 억제를 사용하세요. 그 밖의 경우에는 승인된 기준선을 다시 생성하고 감사하세요. 실제 자격 증명을 절대 억제하지 말고, 커밋되는 설정에 비밀 정보를 넣지 마세요. 기존 언어와 빌드·자동화 체계를 확장하는 방식을 우선하세요. 프로젝트가 이미 지원하는 방식으로 구체적인 요구 사항을 안전하게 충족할 수 없을 때만 의존성이나 새 툴체인을 추가하세요. ## 볼 수 있는 범위와 할 수 있는 작업을 따로 확인하고, 규칙 없는 경로는 거부하기 모든 보호 경로에서 서로 독립적인 두 보안 계층을 유지하세요. - 범위 필터링은 한 주체가 볼 수 있는 리소스를 결정합니다. - 역할 기반 권한 부여는 그 주체가 수행할 수 있는 작업을 결정합니다. 한 계층을 통과했다고 해서 다른 계층을 대신할 수는 없습니다. 플랫폼 공개 범위는 플랫폼 내부의 가시성으로 취급해야 하며, 인터넷의 익명 접근을 허용하는 것으로 취급해서는 안 됩니다. 각 토큰 유형은 하나의 정식 정책 함수로 정규화하세요. 자체 완결형 또는 레거시 API 토큰에서 팀 범위가 누락되거나 비어 있으면 안전하게 닫혀 플랫폼 공개 범위만 보이게 해야 합니다. 관리자 우회에는 명시적인 우회 상태와 검증된 관리자 상태가 모두 필요합니다. 세션 기반 주체에서는 서버에 저장된 구성원 정보와 관리자 상태가 권한의 정본이며, 토큰 클레임은 접근 범위를 좁힐 수만 있습니다. 교집합이 비어 있으면 안전하게 닫혀야 합니다. 신뢰할 수 있는 외부 로그인을 통해 프로비저닝된 주체도 외부 권한 주장을 신뢰하지 말고 저장된 로컬 권한 부여 상태를 사용해야 합니다. 다음 불변 조건을 적용하세요. - 전송 세션을 설정하거나 메시지를 전달하기 전에 인증하고, 작업을 처리하기 전에 작업 권한을 적용하세요. - 명시적인 권한 매핑이 없는 보호 라우트는 기본적으로 거부하세요. - 소유권, 팀, 세션 주체는 인증된 서버 측 상태에서 도출하세요. 클라이언트가 제공한 소유권 필드를 절대 신뢰하지 마세요. - URL 쿼리 매개변수로 들어오는 클라이언트 자격 증명을 절대 받지 마세요. - 고위험 전송 방식과 제한 없는 도메인 간 라우팅은 기본적으로 비활성화하세요. - 게이트웨이 간 트래픽에는 명시적인 도메인 허용 목록을 요구하세요. 빈 허용 목록은 모든 대상을 차단합니다. - 통신하는 게이트웨이가 같은 발급자를 신뢰하도록 하고, 원격 권한 부여에 필요한 자격 증명만 전달하세요. 위임형 토큰 교환에서는 사용자가 보낸 토큰을 하위 서비스로 절대 전달하지 마세요. 신뢰할 수 있는 권한 부여 서버를 통해 교환하고 교환된 토큰만 전달하세요. 설정된 교환 대상을 SSRF 및 외부 통신 경계로 취급하세요. 설정을 저장할 때 검증하고, 설정 변경을 권한 있는 주체로 제한하며, 상관관계 식별자를 기록하고, 원본 수신 토큰이나 교환된 토큰을 절대 로그에 남기지 마세요. 보안에 민감한 변경에는 미인증 접근, 잘못된 범위, 권한 부족, 비활성화된 기능, 허용되지 않은 대상, 그 밖의 거부 경로를 다루는 회귀 테스트가 포함되어야 합니다. ## 추적과 감사 기록의 쓰기를 주 트랜잭션과 분리하기 영속성 코드를 수정하기 전에 의도된 트랜잭션 경계를 이해하세요. 요청 데이터, 관측 가능성 기록, 감사 기록은 의도적으로 서로 다른 세션과 원자성 보장을 사용할 수 있습니다. 최선형 관측 가능성 쓰기는 즉시 커밋하는 수명이 짧은 독립 세션을 사용할 수 있습니다. 이렇게 하면 주 요청이 실패해도 추적 정보와 이벤트가 남지만, 원격 측정 데이터가 요청과 원자적이지 않으며 부분 상태나 진행 중 상태를 표시할 수 있습니다. 조회 작업은 가시성과 권한 부여 필터가 적용되도록 계속 요청 범위 세션을 사용해야 합니다. 감사 로깅도 자체 세션을 소유하고 자체 실패를 격리할 수 있습니다. 편의만을 위해 요청에서 이미 커밋된 세션을 독립 감사 기록기에 전달하지 마세요. 두 번째 커밋이나 롤백은 공유 트랜잭션을 비활성 상태로 만들 수 있으며, 주 리소스가 이미 영속화된 뒤 오류를 노출할 수 있습니다. 감사 기록이 주 쓰기와 원자적이어야 한다면 검토, 새로운 실패 의미, 테스트가 필요한 명시적 설계 변경으로 취급하세요. 독립 추적은 요청마다 여러 데이터베이스 세션을 만들 수 있습니다. 고정된 용량 수치를 복사하지 말고 동시성을 측정하고, 풀 고갈 신호를 감시하며, 실제 데이터베이스와 작업 부하에 맞게 풀 크기를 정하세요. 근거 없이 비동기 핸들러 내부의 의도적인 동기식 영속화 전략을 개별 결함으로 분류하지 마세요. 일부 호출 지점만 변환하면 의미가 섞일 수 있으므로, 드라이버와 트랜잭션을 함께 옮기는 조정된 마이그레이션을 제안하세요. ## 현재 head를 확인한 뒤 데이터베이스 마이그레이션 추가하기 마이그레이션을 만들기 전에 현재 마이그레이션 head를 조회하세요. 새 리비전의 부모는 검증된 head를 참조해야 합니다. 추측하거나 이전 파일에서 부모 식별자를 복사하지 마세요. 만든 후에는 이력에 의도한 head가 정확히 하나만 남아 있는지 확인하세요. 설치 상태가 다를 수 있다면 멱등 마이그레이션 단계를 작성하세요. 수정 전에 현재 스키마를 검사하고, 선택적 테이블이 없으면 안전하게 건너뛰며, 이미 존재하는 열이나 객체를 추가하지 마세요. 새 데이터베이스 생성 경로와 업그레이드 경로를 일관되게 유지하세요. 다운그레이드가 런타임 설정에 의존한다면 환경에 독립적으로 재현 가능하게 만드세요. 1. 업그레이드 중에는 필요한 모든 설정 값을 리비전을 키로 하는 마이그레이션 소유 메타데이터에 저장하세요. 2. 다운그레이드 중에는 현재 환경이 아니라 저장된 스냅샷을 읽으세요. 3. 스냅샷 방식이 생기기 전에 업그레이드된 데이터베이스에 대해서만 현재 설정을 문서화된 호환성 대체 수단으로 사용하세요. 4. 다운그레이드가 끝나면 스냅샷을 제거하세요. 업그레이드 초기 데이터를 넣기 위해서만 설정을 읽는 마이그레이션은 다운그레이드도 그 값에 의존하지 않는 한 다운그레이드 스냅샷이 필요하지 않습니다. 편집 후 head를 다시 검증하고 관련 마이그레이션 및 애플리케이션 테스트를 실행하세요. 대상 데이터베이스가 뒤처져 있다면 새 리비전을 생성하기 전에 통제된 개발 또는 테스트 데이터베이스를 예상 head까지 올리세요. 명시적 권한과 검토된 계획 없이 프로덕션에서 이런 수정 업그레이드를 절대 수행하지 마세요. ## 실제 검사 결과를 확인하고, push 전에 허락 받기 최종 diff를 원래 요청, 가장 가까운 분야별 지침, 위의 보안 불변 조건과 대조해 검토하세요. 해당하는 경우 lint, 타입, 보안 스캔, 테스트, 마이그레이션, 생성 자산, 문서의 실제 결과를 확인하세요. 검사만으로 성공했다고 주장하지 마세요. 저장소가 요구하는 커밋 규칙, 서명 정책, issue 링크, pull request 템플릿을 사용하세요. 명시적인 권한을 받기 전에는 push, force-push, 기여자의 브랜치 수정, 프로젝트 외부 상태 변경을 하지 마세요. 공개 리뷰와 issue 댓글에서는 다음을 지키세요. - 우려를 제기하기 전에 정상적으로 동작하는 점부터 설명하세요. - 차단 사항, 제안, 사소한 메모를 구분하세요. - 불필요한 지시를 내리는 대신 위험을 설명하고 질문이나 선택지를 제시하세요. - 가혹하거나 기계적으로 들리지 않으면서도 문제를 직접적으로 전달하세요. 제품 diff나 공개 메시지에 내부 어시스턴트 표시, 숨겨진 운영 설명, 자격 증명, 추측성 작업량 주장을 추가하지 마세요. 변경에 실제로 필요한 경우에만 새 파일이나 문서를 만드세요. 작업을 분류할 때는 신고자의 정보를 기다리는 요청, 의존성으로 막힌 항목, 승인되었지만 연기된 항목을 구분하세요. 수정 변경이 병합된 뒤에만 issue를 해결됨으로 표시하고, 로컬에서 구현만 된 상태에서는 그렇게 표시하지 마세요. 완료하기 전에 민감한 값이 버전 관리 밖에 있고, 보안 거부 경로에 테스트가 있으며, 정본의 우선순위를 따랐고, 관련 없는 임시 콘텐츠가 diff에 들어오지 않았는지 확인하세요.