계층형 앱 저장소에서 AI 코딩 에이전트가 요청한 범위만 작업하게 한다

## 지시의 우선순위를 정하고, 기억보다 현재 코드를 믿는다 현재 체크아웃이 현재 동작에 대한 진실의 원천이다. 사용자 요청은 원하는 동작 변경을 정의할 수 있지만, 과거의 가정을 사실로 바꿔 주지는 않으며 관련 없는 외부 행동에 대한 허가를 주지도 않는다. ### 지시의 순서 적용되는 상위 지시를 먼저 따르고, 그다음이 가장 가까운 범위의 에이전트 지시 파일, 그다음이 가장 최근의 사용자 요청이다. 같은 권한 수준에서는 더 새로운 명시적 지시가 이긴다. ### 근거의 순서 현재 체크아웃의 동작에 대해서는 현재 소스와 테스트를 우선하고, 그다음이 저장소 내부의 워크플로와 스크립트, 그다음이 문서다. 현재 런타임 상태에 대해서는, 작업 디렉터리·아티팩트·브랜치 또는 그에 준하는 출처 정보가 그것을 의도한 체크아웃과 연결한 뒤에야 실시간 증거를 근거로 인정한다. 다른 체크아웃에서 온, 검증되지 않은 프로세스는 소스가 말해 주는 사실을 뒤집지 못한다. 이전 메모리와 서브에이전트 보고는 직접 확인한 증거보다 아래에 놓이고, 추론이 가장 마지막이다. ### 메모리 규율 이전 메모리와 서브에이전트 출력은 오래되었을 수 있는 단서로 취급한다. 결과에 영향을 주는 주장은 현재 체크아웃과 대조해 검증하고, 메모리가 변경 작업이나 외부 행동을 승인하도록 절대 두지 않는다. 사용자가 명시적으로 요청하지 않는 한 저장소에 관한 영속 메모리를 작성하지 않는다. 비밀정보나 사용자 데이터를 메모리에 절대 담지 않는다. ## 앱 에디션은 실제 설정으로 고르고, 제거한 기능을 되살리지 않는다 어떤 동작은 구현 세부사항이 아니라 제품 계약이다. 다른 작업의 부수 효과로 그것을 변경하지 않는다. ### 실제 런타임 신호로 동작을 선택한다 에디션이나 모드는 문서화된 런타임 속성 또는 빌드 환경 변수로 선택해야 한다. 최종 아티팩트 이름은 아티팩트 이름만 바꿀 뿐이며 결코 런타임 모드의 신호가 아니다. 새로운 런타임 분기는 반드시 실제 신호를 읽어야 한다. 아카이브 이름, 애플리케이션 이름, 포트, 아티팩트 경로로 모드를 절대 추론하지 않는다. ### 출시된 에디션의 경계를 유지한다 게이트웨이 포워딩, 클라우드 계정, 구독, 결제, 상용 라이선스, 대체 데스크톱 런타임을, 그것들을 제거한 에디션에 다시 들여오지 않는다. 프런트엔드 UI를 감추는 것은 백엔드 격리가 아니다. 원격 호출, 헤더, 쿠키, 컨트롤러, 서비스 등록도 에디션 경계를 지켜야 한다. ### 호환되는 의미 체계를 유지한다 명시적인 호환성 변경이나 마이그레이션 변경을 요청받지 않는 한, 공개 API, 스토리지, 데이터소스, 네임스페이스, 콘솔, 태스크, 레이아웃 위치의 의미 체계를 보존한다. 패키징된 데스크톱 빌드가 애플리케이션 내부에서의 업데이트를 지원하는 경우, 릴리스 형식이 바뀔 때마다 렌더러 업데이트 UI와 상태, 네이티브 업데이트 핸들러, 업데이터 메타데이터, 패키징된 페이로드, 그리고 권한이 상승된 업데이터 헬퍼를 서로 어긋나지 않게 맞춘다. ## 구조는 코드 인덱스로, 문자열은 텍스트 검색으로 찾는다 ### 구조에 관한 질문 구조적 코드 인덱스가 초기화되어 있고 그 도구를 쓸 수 있으면, 기능·아키텍처·버그 경로에 대한 컨텍스트 질의로 시작한 다음 관련 소스를 한 번 살펴본다. 이름을 찾을 때는 심볼 조회를, 호출 경로에는 호출자·피호출자 질의를 사용하고, 공유 심볼을 바꾸기 전에는 영향도 질의를 사용한다. 소스 트리 탐색에는 인덱싱된 파일 목록을, 인덱스 상태 점검에는 상태 확인 명령을 사용한다. ### 문자 그대로의 질문 리터럴 문자열, 설정 키, 로그 줄, 주석, 생성된 플래그, 명령줄에는 텍스트 검색을 사용한다. 인덱스로 이미 얻은 결과를 두 번째 검색·읽기 루프로 반복하지 않는다. ### 인덱스의 한계 인덱스는 최근의 쓰기를 뒤늦게 반영할 수 있으며, 정확성의 권위는 여전히 빌드 도구에 있다. 인덱스를 쓸 수 없으면, 인덱싱된 결과가 있는 척하지 말고 범위를 좁힌 파일 읽기와 텍스트 검색을 사용한다. 저장소에 초기화된 인덱스가 없으면, 만들기 전에 물어본다. ## 움직이기 전에 읽기만 하는 요청과 변경 요청을 구분한다 - 답변, 설명, 리뷰, 진단, 상태 확인 요청은 기본적으로 읽기 전용이다. 변경을 일으키지 않는 조사 방법을 사용하고 증거를 보고한다. 요청받지 않는 한 파일을 편집하거나, 변경이 많은 빌드를 실행하거나, 수정을 구현하지 않는다. - 변경·수정·정리 요청은 지정된 범위 안에서의 로컬 소스 편집과 관련 로컬 명령 실행을 승인한다. - 빌드 요청은 빌드 명령, 의존성 캐시, 생성된 산출물만 승인한다. 사용자가 수정도 함께 요청하지 않는 한 소스 수리를 승인하지 않는다. - 커밋, 푸시, 태그, 워크플로 디스패치, 공개 게시, 배포, 서명, 그리고 프로덕션이나 고객 데이터에 손대는 모든 행동은 그 특정한 외부 효과에 대한 명시적 승인을 필요로 한다. ## 승인된 변경을 가장 작은 범위에서 끝까지 마친다 승인된 구현 작업에서는, 일관성을 유지할 수 있는 가장 작은 범위 안에서 요청받은 결과를 끝까지 완성해 전달한다. - 정확한 저장소, 브랜치, 상태, 그리고 기존 사용자 변경 사항을 확인한다. - 편집하기 전에 가장 가까운 구현, 테스트, 설정, 워크플로를 읽는다. 변경이 프런트엔드, 백엔드, 스토리지, 컨테이너, 데스크톱 패키징에 걸쳐 있으면 계층을 넘나드는 동작을 추적한다. - 영향을 받는 표면으로 변경을 분류하고, 그에 맞춰 검증 방법을 고른다. - 기존 모듈 소유권과 로컬 관례를 따르며 좁게 편집한다. - 관련 검사를 실행하고, 최종 diff를 확인하며, 실제로 실행한 검증과 사용할 수 없었던 검사를 구분한다. - 결과, 남아 있는 위험, 그리고 커밋되지 않았거나 푸시되지 않은 정확한 상태를 보고한다. ## 서버와 클라이언트 코드를 각자의 계층과 모듈에 둔다 ### 서버 쪽 컨트롤러와 전송 어댑터는 얇게 유지한다. 비즈니스 동작은 도메인 서비스에 속하고, 영속화는 스토리지 API나 프로바이더 뒤에 속한다. 모듈 의존 방향과 문서화된 계약을 보존한다. 웹 계층에서 스토리지로 곧장 이어지는 새로운 결합으로 도메인 API를 우회하지 않는다. 이미 어떤 모듈이 소유한 동작을 위해 병행 프레임워크나 유틸리티 추상화를 새로 들이는 대신, 프로젝트가 이미 쓰고 있는 언어 레벨과 프레임워크를 사용한다. 데이터베이스별 SQL, 메타데이터, 자동 완성, 타입 동작은 그것을 소유한 플러그인 안에 유지하고, 방언 변경에는 범위를 좁힌 플러그인 테스트를 추가한다. ### 클라이언트 쪽 기존 프런트엔드 스택, 프로젝트 컴포넌트, 서비스 헬퍼를 사용한다. 관련 없는 환경 검사를 여기저기 흩뿌리는 대신, 현재의 런타임 에디션 헬퍼나 문서화된 빌드 환경 변수에서 에디션 조건을 도출한다. 중복된 데스크톱 브리지나 두 번째 렌더러 전송 계층을 추가하지 않는다. 기존 브리지 래퍼를 사용한다. 서비스 응답 계약과 스토리지 키를 보존한다. UI를 없앴다고 해서, 다른 경로가 여전히 사용하는 백엔드 계약을 삭제할 권한이 생기는 것은 아니기 때문이다. 주변 기능이 현지화되어 있다면, 사용자에게 보이는 문자열은 기존 현지화 시스템 안에 둔다. ### 고위험 표면 공유 요청 컨텍스트, 아이덴티티, 격리 경계, 스토리지 라우팅, AI 서비스, 데스크톱 시작 과정에 대한 변경은 호출 경로와 회귀에 대한 명시적 검토를 필요로 한다. ## 비밀정보와 생성 파일을 커밋하지 않는다 ### 민감하거나 재생성 가능한 내용을 절대 커밋하지 않는다 자격 증명, 토큰, 서명 자료, 비공개 URL, 로컬 데이터베이스 내용, 에디터 파일, 런타임 다운로드물, 패키지 매니저 산출물, 프런트엔드 빌드 산출물, 패키징용으로 준비된 콘텐츠, 설치 프로그램을 절대 커밋하지 않는다. ### 비밀정보는 좁게 다룬다 명시적으로 승인된 작업에 필요할 때만 비밀정보를 읽는다. 비밀 값을 출력하거나, 로그에 남기거나, 붙여넣거나, 요약하거나, 저장하지 않는다. 어떤 자격 증명을 다른 저장소, 레지스트리, 계정, 환경에 재사용하지 않는다. ### 실제 데이터를 작업 흐름에 끌어들이지 않는다 빌드나 진단의 편의를 위해 프로덕션 데이터, 사용자 데이터, 관련 없는 로컬 데이터베이스에 접근하거나 그것을 변경하지 않는다. 사용자가 다른 시스템을 명시적으로 범위에 넣지 않는 한, 픽스처나 이름이 정해진 로컬 테스트 데이터소스를 사용한다. ### 네트워크 노출 원격 노출이 명시적으로 요청되고 그 보안 영향과 함께 문서화되지 않는 한, 데스크톱과 호스트에 공개되는 리스너는 루프백에 묶어 둔다. 호스트 공개 정책을 강제하려고 컨테이너에 필요한 내부 바인딩을 바꾸지 않는다. ### 버전 관리 대상과 생성물의 구분 어떤 패키징 리소스가 버전 관리되는 소스이고 어떤 것이 재생성 가능한 산출물인지 파악한다. 생성 파일과 상위 디렉터리를 공유한다는 이유만으로 추적 중인 리소스를 제거하지 않는다. 공개 명령, 포트, 아티팩트, 환경 변수, 릴리스 입력값이 바뀌면 readme와 워크플로 예시를 갱신한다. ## 앱의 어느 부분을 바꿨는지에 따라 테스트와 검사를 고른다 - 프런트엔드 로직, 라우트, 서비스, 상태: 관련된 범위를 좁힌 테스트, 린트 태스크, 에디션 빌드. - 서버 도메인, 웹, 스토리지, 플러그인 코드: 테스트 실행을 명시적으로 켠 상태에서의 범위를 좁힌 테스트, 오래된 테스트 포함 패턴과 실패 무시 설정을 재정의한 상태, 그리고 0이 아닌 테스트 개수 확인. 그런 다음 영향을 받는 모듈과 그 의존성을 패키징한다. - 공유 API 또는 영속성 계약: 호환성 커버리지를 추가하고, 호출자와 함께 직렬화·스토리지 영향을 확인한다. - 런타임 모드, 아이덴티티, 격리, AI, 네트워크 동작: 등록 경로와 호출 경로를 모두 확인하고, 가능하면 에디션 스모크 테스트를 실행한다. - 네이티브 브리지 코드: 범위를 좁힌 브리지 테스트, 전체 컴파일 또는 패키징, 그리고 대응하는 렌더러 검증. - 데스크톱 스크립트와 리소스: 손댄 셸 스크립트를 문법 검사하고, 플랫폼 메타데이터를 검증하고, 준비 단계를 실행하고, 크로스 플랫폼 워크플로를 검토한다. - 컨테이너 작업: 스크립트 문법, compose 확장 결과, 이미지 빌드, 그리고 컨테이너 런타임을 쓸 수 있을 때는 HTTP 또는 정적 자산 스모크 테스트. - 워크플로 정의: 해석된 입력값과 명령을 파싱하거나 확인하고, 아티팩트 업로드와 릴리스 공개 게시와 콘텐츠 전송 업로드를 구분한다. - 문서만 바뀐 변경: 명령, 링크, 경로, 포트, 이름을 현재 소스와 워크플로에 대조해 검증한다. - 모든 변경: 공백과 충돌 마커에 대한 diff 검사, 범위를 좁힌 diff 검토, 그리고 마지막 상태 확인. ## 빌드 성공을 테스트 통과로 말하지 않고, 실제로 돌린 테스트만 보고한다 빌드 성공은 테스트 성공이 아니다. 프로젝트가 기본적으로 테스트를 건너뛰거나, 오래된 테스트 포함 패턴이나 실패 무시 설정을 안고 있다면, 그것들을 명시적으로 재정의하고, 테스트 요약이 0이 아닌 테스트 개수와 실패 0건, 오류 0건을 보고하는지 확인한다. ### 과장하지 않는다 테스트를 건너뛴 채로 호출한 빌드를 두고 그 빌드가 테스트를 실행했다고 주장하지 않는다. 셸 문법 검사나 준비 단계만 가지고 네이티브 패키지가 동작한다고 주장하지 않는다. 설치 프로그램의 성공은 실제로 대상 플랫폼에서 빌드하고 실행해 본 설치 프로그램에 대해서만 주장한다. 더 넓은 테스트 집합을 실행했을 때 모듈의 다른 곳에서 오래된 컴파일 실패가 드러나면, 테스트 탐색 범위를 약화시키지 말고 그 사실을 보고한다. ### 실행하지 않은 것을 명시한다 자동화 환경에서만 가능하거나, 특정 플랫폼에서만 가능하거나, 그 밖의 이유로 실행하지 못한 검사를 따로 떼어 밝힌다. 필요한 도구를 쓸 수 없으면 빠진 검사를 보고하거나 동등한 읽기 전용 대체 방법을 쓴다. 도구 출력을 절대 지어내지 않고, 환경을 말없이 넓히지 않는다. ## 작업에 필요한 서비스와 테스트 데이터베이스만 쓴다 - 승인된 변경이나 빌드 작업에서는 저장소 편집, 생성된 빌드 산출물, 표준 패키지 매니저 캐시, 통상적인 의존성 다운로드가 허용된다. 작업에 그것이 필요하고 그 영향이 명시되지 않는 한, 전역 패키지 매니저 설정을 바꾸거나 시스템 패키지를 설치하지 않는다. - 요청받은 스모크 테스트에 필요할 때만 로컬 서비스를 시작한다. 먼저 포트를 확인하고, 루프백에 바인딩하고, 프로세스를 기록하고, 이 작업을 위해 자신이 시작한 프로세스만 중지한다. 관련 없는 서비스를 절대 재시작하지 않는다. - 컨테이너 빌드 요청에서는 컨테이너 빌드와 그 작업 범위의 테스트 컨테이너가 허용된다. 데몬을 정리하거나, 관련 없는 리소스를 제거하거나, 작업 범위 밖에서 compose 서비스를 시작하지 않는다. - 자율적인 검증에는 이름이 정해진 로컬 또는 테스트 데이터베이스만 사용한다. 공유·스테이징·프로덕션 시스템에서의 스키마나 데이터 변경은 명시적 범위 지정, 복구 계획, 승인을 필요로 한다. - 의존성 해석과 공개 소스 확인을 위한 읽기 전용 네트워크 접근은 필요할 때 허용된다. 인증이 필요한 쓰기, 업로드, 워크플로 디스패치, 메시지 전송, 공개 게시는 사용자의 명시적 권한이 필요한 외부 행동으로 남는다. ## 사용자의 변경을 지키고, 푸시나 릴리스 전에 묻는다 ### 사용자의 작업 트리를 보호한다 자신이 편집해야 하는 파일 안의 변경을 포함해, 관련 없는 사용자 변경을 보존한다. 작업을 단순하게 만들려고 그것들을 리셋하거나, 체크아웃하거나, 정리하거나, 덮어쓰지 않는다. 파괴적인 버전 관리 명령을 사용하지 않으며, 요청받은 범위 밖의 로컬 데이터나 생성된 캐시를 제거하지 않는다. ### 명시적 요청을 요구한다 사용자가 그 행동을 명시적으로 요청하지 않는 한 스테이징, 커밋, 푸시, 태그 붙이기, 워크플로 디스패치, 릴리스 공개 게시, 패키지 업로드, 이미지 푸시를 하지 않는다. 워크플로 디스패치, 릴리스 공개 게시, 이미지 푸시, 콘텐츠 전송 업로드, 롤링 태그 이동, 서명은 명시적 승인 경계 뒤에 있는 외부 변경으로 취급한다. ### 커밋이나 푸시를 요청받았을 때 의도한 의미 단위의 범위만 스테이징하고, 스테이징된 diff를 확인하고, 거기에 자격 증명이나 생성된 산출물이 들어 있지 않은지 검사하고, 해당 검사를 실행하고, 로컬과 원격의 커밋 식별자를 확인한다. ## 인수인계 때 무엇을 바꿨고 어떤 검사를 돌렸는지 적는다 인수인계 시점에는 어떤 동작이 바뀌었고 어떤 파일이 그것을 소유하는지, 실제로 실행한 명령은 무엇이며 그것이 통과했는지, 자동화 환경에서만·특정 플랫폼에서만 가능하거나 그 밖의 이유로 실행하지 못한 검증은 무엇인지, 손대지 않고 남겨 둔 무관한 수정 사항을 포함한 현재의 버전 관리 상태는 어떤지, 그리고 시도한 모든 외부 행동을 그 커밋·원격 브랜치·워크플로 실행·이미지·릴리스·아티팩트 식별자와 함께, 부분적으로 끝났거나 실패한 시도까지 포함해 밝힌다. ### 코드 리뷰 보고 코드 리뷰에서는 발견 사항을 심각도 순으로 먼저 보고하고, 각각에 그 파일과 줄 번호, 영향을 받는 런타임 표면, 동작상의 위험, 그리고 필요한 수정 또는 빠져 있는 증거를 붙인다. 발견 사항이 없으면 없다고 말하고, 남아 있는 테스트 공백을 나열한다. ## 멈추고 물어볼 때와, 실패 후 다시 시도하는 방법을 정한다 요청받은 범위 안에서의 통상적인 읽기, 편집, 빌드, 테스트 작업은 자율적으로 계속한다. 다음 조건 중 하나가 결과를 실질적으로 바꿀 때만 멈추고 질문한다: - 적용되는 지시들이 서로 충돌하거나, 현재 소스가 기존 동작을 확인해 준 뒤에도 원하는 동작이 여전히 모호할 때 - 작업이 사용자 데이터 삭제, 공개 호환성 계약 변경, 리스너 노출, 에디션 경계를 넘는 일을 필요로 할 때 - 자격 증명, 서명 아이덴티티, 릴리스 대상, 프로덕션 권한이 없을 때 - 되돌릴 수 없거나 외부에 드러나는 행동이 명시적으로 요청되지 않았을 때 - 관련 없는 사용자 편집 때문에 요청받은 변경을 안전하게 분리할 수 없을 때 - 진단과 복구를 한 차례 거친 뒤에도 필요한 검증이 여전히 실패하고, 범위 안에서 안전하게 복구할 방법이 남아 있지 않을 때 ### 재시도와 중단 일시적이고 멱등한 작업은 최대 두 번까지만 재시도한다. 결과가 불명확한 뒤에 푸시, 워크플로 디스패치, 릴리스, 업로드, 서명 요청, 그 밖의 외부 변경을 무작정 반복하지 않는다. 먼저 원격이나 제공자 쪽 상태를 확인한다. 중단되었거나 일부만 완료된 뒤에는 재개하기 전에 브랜치, 워크트리, 원격, 워크플로 상태를 다시 확인한다. ### 실패했을 때 워크트리를 복구 가능한 상태로 유지하고, 정확한 명령과 오류를 기록하고, 근거 없는 성공 주장을 피하며, 현재의 목표, 증거, 이미 시도한 행동, 식별자, 열려 있는 위험, 다음의 안전한 조치를 인수인계한다.