집
code-quality
tursodatabase/turso
일반적인 정확성 규칙, 러스트 패턴, 주석 작성법, 과도한 설계 회피 방법 등을 코딩할 때 항상 고려해야 합니다.
...모든 것을 확장하십시오코드 품질에 대하여
code-quality는 Turso(Limbo) 데이터베이스 프로젝트를 위한 간결한 코딩 규약 참고 자료로, 기여자들이 코드를 작성할 때 반드시 준수해야 할 정확성 관련 규칙, Rust 고유의 작성 스타일, 주석 작성 방법 및 과도한 설계를 피하는 지침들을 담고 있습니다. 이 가이드의 기본 원칙은 정확성이 최우선시되는 실제 운영용 데이터베이스라는 점에 있으며, 데이터 손상보다는 시스템 크래시가 낫기 때문에 코드베이스의 안전성을 유지하는 습관들을 명문화한 것입니다.
이 가이드에서는 정확성 관련 규칙(우회 방법이나 임시 해결책 사용 금지, 자주 assert 사용, 데이터 무결성에 위험을 초래하는 잘못된 상태에서는 즉시 크래시 발생, 엣지 케이스 고려)과 Rust 관련 패턴(불법적인 상태를 표현할 수 없도록 만들기, 철저한 패턴 매칭, 문자열/센티널 대신 열거형 사용, 힙 할당 최소화, CPU 성능에 유리한 코드 작성)을 제시합니다. 또한 절대 실행되어서는 안 되는 분기 경로의 경우 조용히 무시하는 대신 assert!, 오류 반환, unreachable!를 사용하도록 구체적인 지침을 제공하며, ‘무엇’이 아닌 ‘왜’에 초점을 맞춘 주석 작성 규칙과 함께 AI 대화 내용이나 시간 관련 표시를 사용하는 것을 금지합니다. 또한 SQLite와의 인덱스 변경 순서를 반드시 다시 확인하여 불일치가 발생하지 않도록 주의하라고 경고하며, 관련된 비동기 I/O 모델에 대한 정보와 불필요한 코드나 역호환성을 위한 임시 해결책을 남기지 않는 정리 규칙도 함께 제공합니다.
이 가이드는 Turso/Limbo Rust 코드베이스에 기여하는 사람들뿐만 아니라, 체계적인 정확성 점검 목록을 원하는 시스템 수준의 Rust를 작성하는 모든 개발자를 대상으로 합니다. 이 문서는 순수하게 참고용 자료일 뿐 스크립트, 명령어, 인증 정보나 부작용이 전혀 없어 완전히 안전합니다.
FAQ
핵심 원칙은 무엇인가요?
이곳은 정확성이 최우선시되는 실제 운영용 데이터베이스이므로, 데이터 손상보다는 시스템 크래시가 낫습니다. 따라서 정의되지 않은 상태에서 계속 작동하는 대신 명확하게 오류를 발생시키도록 규칙들이 설정되어 있습니다.
절대 발생해서는 안 되는 분기 경로는 어떻게 처리해야 하나요?
조용히 무시하지 마십시오. 상수 메시지와 함께 assert!를 사용하거나 오류를 반환하고, unreachable!를 사용하세요. 두 분기 모두 예상되는 경로인 경우에만 일반적인 if/else 구조를 사용하면 됩니다.
주석 작성 규칙은 무엇인가요?
‘무엇’이 아닌 ‘왜’에 초점을 맞춰 문서화해야 하며, 함수, 구조체, 열거형, 변형체에 대한 설명도 함께 기록해야 합니다. 또한 코드를 반복하는 주석이나 AI 대화 내용을 참조하는 주석, ‘added’나 ‘Phase 1’과 같은 시간 관련 표시가 포함된 주석은 피해야 합니다.
Turso 외의 프로젝트에도 적용되나요?
이 가이드는 Turso/Limbo Rust 코드베이스를 위해 작성되었지만, 그 안에 담긴 정확성 관련 규칙과 Rust 고유의 작성 스타일 지침들은 시스템 수준의 Rust 개발에서도 널리 활용될 수 있습니다.
왜 인덱스 변경 순서에 대해 강조하나요?
삽입, 삭제, 충돌 해결 작업의 순서는 반드시 SQLite와 일치해야 하기 때문입니다. 잘못된 순서는 쉽게 눈에 띄지 않는 인덱스 불일치를 유발할 수 있습니다.
Core Principle
Production database. Correctness paramount. Crash > corrupt.
Correctness Rules
- No workarounds or quick hacks. Handle all errors, check invariants
- Assert often. Never silently fail or swallow edge cases
- Crash on invalid state if it risks data integrity. Don't continue in undefined state
- Consider edge cases. On long enough timeline, all possible bugs will happen
Rust Patterns
- Make illegal states unrepresentable
- Exhaustive pattern matching
- Prefer enums over strings/sentinels
- Minimize heap allocations
- Write CPU-friendly code (microsecond = long time)
If-Statements
Wrong:
if condition { // happy path} else { // "shouldn't happen" - silently ignored}
Right:
// If only one branch should ever be hit:assert!(condition, "invariant violated: ...");// ORreturn Err(LimboError::InternalError("unexpected state".into()));// ORunreachable!("impossible state: ...");
Use if-statements only when both branches are expected paths.
Comments
Do:
- Document WHY, not what
- Document functions, structs, enums, variants
- Focus on why something is necessary
Don't:
- Comments that repeat code
- References to AI conversations ("This test should trigger the bug")
- Temporal markers ("added", "existing code", "Phase 1")
Avoid Over-Engineering
- Only changes directly requested or clearly necessary
- Don't add features beyond what's asked
- Don't add docstrings/comments to unchanged code
- Don't add error handling for impossible scenarios
- Don't create abstractions for one-time operations
- Three similar lines > premature abstraction
Index Mutations
When code involves index inserts, deletes, or conflict resolution, double-check the ordering against SQLite. Wrong ordering causes index inconsistencies. and easy to miss.
Ensure understanding of IO model
- Async IO model
Cleanup
- Delete unused code completely
- No backwards-compat hacks (renamed
_vars, re-exports,// removedcomments)
모든 파일
0개 파일code-quality 설치
클라우드의 .claude/skills/ 디렉터리에 해당 스킬 파일들을 다운로드하여 압축을 풀어주세요.
ZIP 다운로드저장소를 클론하고 스킬 파일을 프로젝트에 복사하세요.
git clone https://github.com/tursodatabase/turso/blob/main/.claude/skills/code-quality/SKILL.md # Copy SKILL.md to your .claude/skills/ directory
복사
