타입 안전 Web 프레임워크를 고치고 데이터베이스 코드를 세 계층으로 나누기

## 저장소가 정한 개발 환경에 들어가 바꿀 패키지 찾기 전역에 설치된 도구에 의존하지 말고 저장소에서 선언한 환경 관리자를 통해 개발 환경에 진입하세요. ### 환경 설정 - 저장소 루트에서 시작해 승인된 개발 셸을 활성화하세요. - 더 빠르게 명령을 반복할 수 있다면 환경에 캐시된 실행 경로를 사용하세요. - 컴파일러, 패키지 관리자, 데이터베이스 도구, 문서화 도구가 버전이 고정된 환경에서 제공되는지 확인하세요. - 관련 패키지 또는 문서 구성에 선언된 런타임 버전을 사용하세요. - 로컬 진단에 필요할 때만 디버그 로깅을 활성화하고 디버그 모드를 프로덕션 기본값으로 취급하지 마세요. ### 작업 컨텍스트 다중 패키지 저장소에서는 명령을 실행하기 전에 변경을 담당하는 패키지를 식별하세요. 모든 패키지가 하나의 워크플로를 공유한다고 가정하지 말고 해당 패키지의 소스 디렉터리, 테스트 진입점, 생성된 산출물, 공개 모듈, 로컬 지침을 파악하세요. ## 먼저 타입을 빠르게 확인하고 마지막에 전체 테스트 돌리기 반복 작업 중에는 가장 빠르고 신뢰할 수 있는 피드백 루프를 사용한 다음 인계에 필요한 더 광범위한 공식 검증을 실행하세요. ### 집중적인 반복 작업 - 전체 환경 빌드에 비용이 많이 들 때는 빠른 타입 피드백을 위해 대화형 컴파일러, 타입 검사기 또는 모듈 로더를 우선 사용하세요. - 초기 반복 작업에서는 변경된 모듈이나 집중 테스트 진입점만 불러오세요. - 표준 입력을 읽는 대화형 도구에는 명령과 명시적인 종료 경로를 제공해야 합니다. 그렇지 않으면 무기한 대기할 수 있습니다. - 대화형 세션이 다시 불러오기를 지원한다면 편집 후 전체 환경을 반복해서 다시 빌드하지 말고 해당 세션을 재사용하세요. ### 테스트 등록 - 새 테스트를 패키지의 공식 테스트 집계기 또는 검색 구성에 추가하세요. - 집중 테스트가 해당 진입점을 통해 실제로 실행되는지 확인하세요. - 변경이 준비되었거나 공유 동작, 빌드 구성 또는 패키지 경계에 영향을 준다면 전체 저장소 검증을 실행하세요. - 집중 컴파일 검사를 전체 테스트 모음이 통과했다는 증거로 제시하지 마세요. ### 개발 서버 승인된 환경과 올바른 작업 디렉터리에서만 로컬 서비스를 시작하세요. 개발 서버가 호스트 애플리케이션 또는 상위 디렉터리에 의존한다면 진입점을 호출하기 전에 해당 컨텍스트를 명시적으로 설정하세요. ## 패키지마다 맡은 일을 나누고 공개 모듈은 최소로 두기 특히 런타임, 개발 도구, 템플릿, 마이그레이션, 동기화, 애플리케이션 프로그래밍 인터페이스, 테스트, 선택적 통합을 결합한 저장소에서는 코드를 변경하기 전에 책임을 배치하세요. ### 책임 지도 - 서버 시작과 미들웨어를 프레임워크 구성과 분리하세요. - 라우팅과 URL 생성을 타입 안전하게 유지하고 요청 처리에서 분리하세요. - 모델, 검증, 인증, 백그라운드 작업, 저장소, 메일, 실시간 업데이트를 책임별로 분리하세요. - 아키텍처에서 코드 생성, 스키마 설계, 개발 서버 동작을 도구로 정의한다면 이를 핵심 런타임 패키지 밖에 두세요. - 선택적 통합과 서버 측 컴포넌트의 종속성을 핵심으로 유출하지 말고 별도 패키지로 취급하세요. ### 공개 인터페이스 사용자가 필요로 하는 가장 작고 안정적인 모듈 표면만 노출하세요. 원시 명령문, 내부 구성, 헬퍼 전처리부, 구현 모듈은 비공개로 유지해 호출자를 깨뜨리지 않고 발전할 수 있게 하세요. 공개 모듈과 함수에는 프로젝트의 표준 API 문서를 추가하세요. ### 언어 규칙 순수 값, 컨텍스트 매개변수, 필드 접근, 템플릿, 타입 수준 라우팅, 모델 타입에 관해 코드베이스에서 확립된 관용구를 따르세요. 일관성을 떨어뜨리는 동등한 형식보다 프로젝트에서 이미 사용하는 규칙을 우선하세요. ## 값을 쿼리 문에 직접 넣지 말고 밖에는 session 계층만 보이기 인코딩, 원자성, 연결의 소유권을 명시하여 데이터베이스 접근을 명령문, 트랜잭션, 세션 계층으로 구성하세요. ### 명령문 계층 - 원시 매개변수화 쿼리를 입력 인코더와 결과 디코더와 함께 유지하세요. - 런타임 값을 쿼리 텍스트에 삽입하지 말고 모든 런타임 값에 자리표시자를 사용하세요. - 널 허용 여부와 데이터베이스 타입을 명시적으로 인코딩하세요. - 예상 카디널리티에 맞는 디코더를 선택하세요. 선택적 단일 행, 필수 단일 행 또는 여러 행입니다. - 명령문 캐싱 결정은 명령문 정의와 함께 유지하세요. ### 트랜잭션 계층 - 명령문을 원자성이 필요한 비즈니스 작업으로 구성하세요. - 분기 규칙, 존재 여부 검사, 생성 결정이 하나의 일관된 상태를 관찰해야 한다면 트랜잭션 안에 유지하세요. - 호출자가 기존 레코드와 새로 생성된 레코드를 구분할 수 있도록 멱등 결과를 명시적으로 나타내세요. - 작업이 실제로 독립적이고 의도한 트랜잭션 의미를 보존할 때만 독립적 구성이나 선택적 구성을 사용하세요. ### 세션 계층 - 세션 계층을 공개 데이터베이스 인터페이스로 제공하세요. - 원시 명령문과 내부 트랜잭션은 숨긴 채 세션이 연결 실행과 트랜잭션 경계를 소유하게 하세요. - 여러 명령문으로 이루어진 작업에는 명시적 트랜잭션을 사용하고 하나의 독립 쿼리에는 명령문 직접 실행을 사용하세요. ## 데이터베이스 작업마다 분리 수준과 결과 타입 맞추기 모든 곳에 하나의 패턴을 적용하지 말고 작업의 의미에 맞게 격리, 카디널리티, 결과 타입을 조정하세요. ### 격리 선택 - 정확성이 직렬화에 의존하는 중요 작업에는 강한 쓰기 트랜잭션을 사용하세요. - 동시성이 중요하고 더 약한 격리를 허용할 수 있는 쿼리에는 적절한 읽기 격리 수준을 사용하세요. - 정확성이 특정 격리 모드에 의존하는 모든 작업을 문서화하세요. ### 결과 규칙 - 행이 없거나 하나인 결과는 선택적 값으로 나타내세요. - 여러 행의 결과는 프로젝트의 표준 시퀀스 타입으로 나타내세요. - 이름이 있는 래퍼가 유용한 경계를 추가하지 않는다면 작은 내부 다중 열 결과에 튜플을 사용하세요. - 업데이트 또는 삭제가 아무 행에도 영향을 주지 않을 수 있다면 명시적 성공 표시를 반환하세요. - 멱등 작업에서는 작업 수행 여부와 결과 값을 모두 반환하세요. ### 코덱 구성 인코더 라이브러리가 중첩된 쌍을 구성할 때는 평면 입력 튜플을 의도적으로 조정하고 매핑을 명령문 옆에 유지하세요. 열 순서, 널 허용 여부, 행 카디널리티가 보존되도록 디코더를 구성하세요. 값을 잘못된 필드에 조용히 매핑할 수 있는 불일치에 대해 집중 테스트를 추가하세요. ## 종속성은 쓰는 패키지에만 추가하고 force-push는 하지 않기 변경을 호환 가능하고 검토 가능하며 복구할 수 있게 유지하세요. ### 코드와 종속성 - 기여자의 이해를 높인다면 프로젝트에서 선호하는 언어 형식을 사용하세요. - 공개 인터페이스를 저장소의 표준 문서화 시스템으로 문서화하세요. - 코드베이스에서 활성화된 언어 확장을 존중하고 구체적인 필요 없이 새 확장을 도입하지 마세요. - 종속성은 이를 사용하는 패키지에만 추가하세요. - 지원되는 생태계에 적합한 호환성 하한과 상한을 선언하세요. - 실험적 종속성을 명시적 위험으로 취급하고 좁은 인터페이스 뒤에 격리하세요. ### Git 안전 - `force-with-lease`를 포함해 절대로 `force-push`하지 마세요. - 원격 브랜치가 앞서 나갔다면 `fetch`한 뒤 업데이트된 기록 위에 `rebase`하거나 `merge`하고, 충돌을 해결하고, 검증한 다음 일반적인 `push`를 수행하세요. - 공유 기록을 다시 작성해 거부된 `push`를 숨기지 마세요. - 관련 없는 생성 파일, 잠금 파일 변경, 로컬 성능 설정은 커밋에 포함하지 마세요. ## 로컬 재정의는 커밋에서 빼고 문서는 릴리스 절차로 배포하기 개발 중에는 로컬 성능 및 종속성 재정의를 사용하되 공유 소스 제어로 유출되지 않게 하세요. ### 로컬 성능 재정의 - 프로젝트에서 지원한다면 로컬 반복 작업을 위해 임시 빠른 빌드 플래그를 활성화할 수 있습니다. - 로컬 전용 성능 변경을 커밋하지 마세요. - 인계 전에 변경을 숨길 수 있는 인덱스 플래그에만 의존하지 말고 실제 diff를 조사하세요. ### 로컬 종속성 개발 프레임워크와 이를 사용하는 애플리케이션을 함께 개발할 때는 다음을 따르세요. 1. 로컬 프레임워크 체크아웃을 의도적으로 정한 개발 위치에 두세요. 2. 지원되는 재정의 메커니즘을 통해 애플리케이션 종속성이 해당 로컬 경로를 가리키게 하세요. 3. 필요한 환경을 활성화하고 종속성 상태를 새로 고치세요. 4. 로컬 프레임워크를 대상으로 애플리케이션을 테스트하세요. 5. 공유 변경을 준비하기 전에 재정의를 제거하거나 의도적으로 문서화하세요. ### 문서화와 릴리스 - 지정된 환경에서 문서를 로컬로 미리 보세요. - 게시 문서를 별도로 유지한다면 승인된 저장소 워크플로를 통해 해당 프레임워크 또는 문서 종속성을 업데이트하세요. - 해당 업데이트에 필요한 잠금 파일이나 소스 변경만 커밋하세요. - 지정된 릴리스 절차를 통해서만 문서 또는 인프라를 배포하고 종속성 업데이트, 커밋된 상태, 배포 사이의 필수 순서를 유지하세요. - 프레임워크 릴리스에 하위 문서 동기화가 필요하다면 기억에 의존하지 말고 해당 단계를 릴리스 점검 목록에 포함하세요.