타입 기반 모노레포를 망가뜨리지 않고 고치고, 프로젝트 Wiki를 최신으로 유지하기

## 변경이 닿는 패키지·테스트·문서를 먼저 찾기 루트의 에이전트 지침을 모든 코딩 에이전트가 따르는 공유 계약으로 취급하세요. 도구별 지침 파일은 내용을 중복하지 말고 간결하게 유지하며 이 계약을 따르도록 하세요. - 핵심 패키지, 선택적 연동 기능, 개발자 도구, 생태계 모듈, 예제, 문서, 테스트가 어디에 있는지 확인하세요. - 리포지토리에 별도 규정이 없다면 테스트와 픽스처는 대상 패키지 가까이에 있다고 예상하세요. - 하위 시스템을 편집하기 전에 가장 가까운 패키지 지침을 읽으세요. - 파일을 수정하기 전에 요청된 변경을 담당 패키지, 공개 인터페이스, 테스트, 문서까지 추적하세요. - 영향 범위를 가능한 한 작게 유지하고, 범위가 정해진 작업을 리포지토리 전체 재작성으로 확대하지 마세요. ## 리포지토리가 정한 패키지 매니저와 스크립트 쓰기 리포지토리가 선언한 패키지 관리자, 워크스페이스 정의, 런타임 버전, 스크립트를 사용하세요. 익숙한 대체 도구가 로컬에 설치되어 있다는 이유만으로 이를 교체하지 마세요. - 문서화된 설치 명령으로 워크스페이스를 준비하세요. - 전체 검사에는 루트의 build, test, lint, type-check 스크립트를 사용하세요. - 특정 패키지만 다룰 때는 지원되는 워크스페이스 필터를 사용하세요. - 래퍼가 하위 도구로 옵션을 넘길 때 인수 전달 방식을 정확히 유지하세요. - 패키지 관리자나 런타임에 관한 전제를 바꾸기 전에 리포지토리 구성 파일을 확인하세요. - 범위가 더 좁은 명령이 의존하는 전제 조건을 기록하세요. ## CI와 같은 순서로 테스트하고 오래된 빌드 출력 섞지 않기 임의의 로컬 순서를 만들지 말고 지속적 통합의 실행 순서를 재현하세요. CI가 의존성을 설치한 뒤 먼저 빌드하지 않고 검증 명령을 실행한다면, 테스트도 같은 순서로 실행하세요. - 생성된 출력이 소스 파일과 함께 발견될 수 있다면 먼저 빌드하지 마세요. - 등록 중복, 스키마 중복, 데코레이터가 적용된 클래스 중복 오류는 소스 파일과 생성된 파일이 모두 로드되었다는 증거일 수 있습니다. - 의존성, 테스트, 픽스처는 제외하고 문서화된 소스 루트 아래의 생성된 출력 디렉터리만 제거하세요. - 생성된 출력으로 인한 오류를 해결하려고 소스 디렉터리를 삭제해서는 안 됩니다. - 구현 코드를 변경하기 전에 정리 후 실패한 테스트를 다시 실행하세요. - 정리 후에도 오류가 달라지지 않으면 새로 얻은 증거를 바탕으로 일반적인 디버깅을 계속하세요. ## 기존 코드 스타일을 따르고 앱 상태를 전역에 두지 않기 새로운 추상화를 만들기보다 리포지토리의 기존 패턴을 우선하세요. 코드베이스가 이미 채택한 모듈 시스템, 타입 언어 규칙, 포매터, 린터, 파일 이름 형식을 사용하세요. - 리포지토리 규칙이라면 파일 이름을 소문자와 하이픈으로 구성하세요. - 공개 API 변경은 의도적으로 수행하고 테스트로 보호하며 문서화하세요. - 애플리케이션별 가변 런타임 상태는 프로세스 전역 싱글턴이 아니라 애플리케이션이 소유한 스코프에 보관하세요. - 수명 주기 유틸리티와 기타 애플리케이션별 서비스에는 프레임워크의 스코프 지정 저장소를 사용하세요. - 타이머, 이벤트 리스너, 프록시 핸들러, 모듈 수준 이탈 지점처럼 분리된 콜백에서는 소유 애플리케이션의 스코프로 다시 진입하세요. - 올바른 애플리케이션 컨텍스트에 이미 고정된 접근자에 중복 스코프 래퍼를 추가하지 마세요. ## 시작할 때 읽는 모듈이 시작 스냅샷을 깨지 않게 하기 런타임이 시작 스냅샷을 직렬화할 수 있다면 빌드 시점 부팅이 정상적인 애플리케이션 시작 전에 멈출 수 있다고 가정하세요. 이 단계에서 로드되는 모든 모듈은 안전하게 직렬화할 수 있어야 합니다. - import 시점이나 부팅 시점 작업이 직렬화할 수 없는 네이티브 상태를 만든다면 해당 모듈을 외부화하세요. - HTTP 파서, HTTP/2 바인딩, TLS 컨텍스트, DNS 채널, WebAssembly 인스턴스, 파일 감시기, 네이티브 애드온, 열린 소켓을 스냅샷에 위험한 의존성으로 취급하세요. - 외부화한 모듈은 런타임의 복원 시점 로딩 브리지를 통해 불러오세요. - 지연 로드하거나 외부화 상태로 유지해야 하는 모듈의 문서화된 기본 목록을 하나만 관리하세요. - 생성된 출력에 패치를 적용하지 말고 리포지토리가 지원하는 구성을 통해 그 목록을 확장하세요. - 네이티브 상태의 직접 생성과 전이적 네트워크 사용을 구분하세요. 지연 외부화된 내장 모듈이 전이적 의존성을 이미 보호할 수 있지만, 네이티브 상태나 WebAssembly 상태를 직접 만드는 패키지는 여전히 명시적으로 처리해야 합니다. - 프레임워크 의존성이 부팅 중 네이티브 스택이나 네트워크 스택에 접근할 수 있다면 스냅샷 빌드 테스트를 추가하세요. ## 전역 타입 추가를 전용 타입 모듈에 모으기 패키지 전체의 전역 확장은 전용 전역 타입 모듈에 두세요. 여러 패키지에서 사용하는 공유 확장은 단일 사용 패키지가 아니라 공유 타입 패키지에 두세요. - 선언 파일에 import, 타입 전용 import 또는 빈 export를 두어 모듈로 유지하세요. - 해당 타입 공개 범위가 필요한 패키지의 진입점에서 공유 확장을 import하세요. - 파일에 모듈 구문이 없다는 이유만으로 전역이 되는 앰비언트 선언을 피하세요. - 공유 타입을 옮긴 뒤에는 정의 패키지와 사용하는 패키지 하나 이상을 모두 테스트하세요. - 공개 타입 범위의 모든 변경을 문서화하세요. ## 필요한 테스트를 돌리고 최종 diff를 확인한 뒤 보고하기 변경한 동작을 입증하는 가장 범위가 좁은 검사를 먼저 실행하고, 영향을 받는 경계에서 필요할 때만 범위를 넓히세요. - 로더, 애플리케이션 수명 주기, 클러스터링, 에이전트, HTTP 처리, 프로세스 동작을 변경할 때는 회귀 테스트를 추가하세요. - 리포지토리 스크립트를 통해 포매팅, lint, 타입 검사, 관련 테스트를 실행하세요. - 리포지토리의 커밋 메시지 규칙을 사용하고 범위를 정확하게 유지하세요. - 변경 설명에 동기, 변경된 동작, 위험, 테스트 증거를 적으세요. - 최종 차이에서 무관한 편집, 생성된 잡음, 문서화되지 않은 공개 변경을 확인하세요. - 관련 명령이 성공적으로 완료되기 전에는 성공했다고 보고하지 마세요. ## 비밀 정보를 커밋하지 않고 취약점 공개 전에 멈추기 취약점 관련 작업을 처리하기 전에 리포지토리 보안 정책을 읽으세요. 비밀 정보, 자격 증명, 비공개 엔드포인트, 장치별 구성을 절대 커밋하지 마세요. - 로컬 런타임과 패키지 관리자 버전을 리포지토리 선언에 맞추세요. - 잠금 파일과 워크스페이스 구성을 서로 연동되는 입력으로 취급하고, 의도적인 의존성 또는 툴체인 업데이트에만 변경하세요. - 예제와 문서에서는 실제 자격 증명이나 비공개 URL 대신 자리표시자를 사용하세요. - 보안에 민감한 변경은 범위를 좁게 유지하고 보호 경계에 회귀 테스트를 추가하세요. - 작업에서 명시적으로 허가하지 않았다면 취약점 세부 정보를 공개하거나 보호된 외부 시스템을 변경하기 전에 멈추세요. ## 코드 같은 근거 자료, Wiki, AI 규칙을 나누어 두기 서로 다른 세 가지 지식 계층을 유지하세요. 가공 전 출처는 권위 있는 증거이고, Wiki는 지속적으로 활용할 종합 지식을 보관하며, 루트 에이전트 지침은 공유 워크플로 규칙을 정의합니다. - 코드, 사용자 대상 문서, 루트 프로젝트 파일, 명시된 외부 산출물, 가져온 가공 전 자료를 출처 증거로 취급하세요. - 개요를 파악할 때는 Wiki 요약에서 시작하되 세부 사항, 충돌, 최신성이 중요하면 가공 전 출처로 검증하세요. - 작업에서 요구하지 않는 한 가공 전 출처를 다시 작성하지 마세요. - 반복해서 사용하는 외부 증거는 리포지토리 지식 베이스에 보관하세요. - 충돌을 거짓 합의로 평준화하지 말고 명시적으로 기록하세요. - 도구별 에이전트 파일은 간결하게 유지하고 공유 스키마를 참조하게 하세요. ## Wiki 페이지마다 주제 하나와 출처 파일 적기 실질적인 각 지식 페이지에는 명확한 주제를 하나만 두고 package, concept, workflow, decision, source 같은 페이지 유형을 선언하세요. - 소문자와 하이픈으로 구성된 파일 이름을 사용하세요. - 사람이 읽을 수 있는 제목, 페이지 유형, 한 줄 요약, 주요 출처 경로, 현지 달력 날짜, 최신성 상태를 포함하는 프런트매터를 두세요. - 중요하고 자명하지 않은 주장에는 추적 가능한 출처 파일을 제시하세요. - 자명하지 않은 종합 판단은 추론이라고 표시하세요. - 최신성이 불확실한 주장은 오래되었거나 미해결 상태라고 표시하세요. - Wiki 색인을 간결하게 유지하고 범주별로 정리하세요. - 대규모 자료 반입, 지속적인 발견, 중요한 재구성, 기록된 이해를 바꾸는 변경에는 추가 전용 로그를 사용하세요. - 단순한 오타 수정은 로그에 기록하지 마세요. ## 자료를 넣거나 질문에 답하기 전에 Wiki 색인 먼저 읽기 출처 반입, 리포지토리 관련 질문에 대한 답변, 지식 베이스의 린트 검사에 예측 가능한 워크플로를 사용하세요. - 반입 작업에서는 색인을 읽고, 자료를 흡수해야 할 기존 페이지를 찾고, 필요하면 source 페이지를 만들거나 갱신하고, 영향받는 페이지와 색인을 갱신하며, 중요한 변경에는 로그 항목을 추가하세요. - 질의 작업에서는 먼저 색인과 관련 Wiki 페이지를 읽고, 가공 전 출처로 검증하며, 새로 얻은 지속적인 지식을 다시 기록하고, 중요한 지식 변경을 로그에 남기세요. - 린트 검사에서는 고립된 페이지, 오래된 주장, 중복 개념, 출처 참조 누락, 자주 다루는 영역의 페이지 부족, 모순을 확인하세요. - 겹치는 페이지를 끝없이 길게 만들기보다 구조를 다시 정리하세요. - 기반 패키지, 연동 기능, 도구, 수명 주기 동작, 로딩, 테스트, 릴리스 작업, 문서 유지보수에 관한 지속적 지식을 우선하세요. ## API나 작업 흐름이 바뀔 때만 Wiki 갱신하기 작업으로 공개 API, 문서 구조, 패키지 책임, 아키텍처, 반복되는 기여자 워크플로, 테스트 기대 사항, 릴리스 절차가 실질적으로 바뀌면 지식 베이스를 갱신하세요. - 지속적인 이해를 바꾸지 않는 코드 전용 변경으로 Wiki를 불필요하게 갱신하지 마세요. - 새 규칙이 광범위하게 적용되면 같은 변경에서 기여자 지침도 갱신하세요. - 출처 경로와 최신성 날짜를 이를 뒷받침하는 사실과 동기화하세요. - 지식 변경이 향후 작업에 도움이 될 만큼 중요할 때만 로그 항목을 추가하세요. - 완료를 보고하기 전에 최종 문서를 구현된 동작과 대조해 검증하세요.