seiso의 기능
seiso는 AI가 작성하고 사람과 코딩 에이전트가 읽는 프로젝트 문서를 위한 Markdown 규칙이자 린터입니다. 저장소의 문서를 일관되고 유지 관리하기 쉽게 만들며, 향후 변경 작업의 컨텍스트로 더 쉽게 활용할 수 있도록 돕습니다.
이 도구는 모든 프로젝트가 각자의 문서 규칙을 만들도록 요구하는 대신, 공유 규칙에 따라 문서를 검사합니다. 각 문서는 howto, reference, adr와 같은 종류를 선언하고, 해당 종류에 적합한 내용만 포함합니다.
seiso는 각 사실에 하나의 권위 있는 출처를 두도록 권장합니다. 다른 페이지는 같은 정보를 반복하는 대신 해당 출처로 연결해야 합니다. 이를 통해 특히 AI가 생성한 문서가 여러 파일에 필드 목록, 버전, 상태 또는 개수를 복사할 때 발생하는 모순을 줄일 수 있습니다.
문서화의 핵심 원칙
- 모든 문서는 하나의 종류를 선언하고 해당 종류의 목적을 따릅니다. how-to 문서는 단계를 설명하고, 설계 근거는 ADR에 기록합니다.
- 각 사실에는 하나의 출처가 있습니다. 다른 문서는 이를 다시 설명하는 대신 권위 있는 페이지로 연결합니다.
- 오래 유지되는 페이지에는 페이지보다 빠르게 변하는 값이 들어가지 않도록 합니다. 여기에는 버전, 배포 상태, 개수 등이 포함됩니다.
- 문장에서 구체적인 구현 세부 사항을 언급할 때는 포인터로 파일이나 심볼을 식별합니다.
- 완성된 문서는 문서 작성을 요청한 사람에게 말을 걸거나 문서가 어떻게 만들어졌는지 서술해서는 안 됩니다.
- 도구가 판단할 수 없는 결정은 이유와 함께 기록해야 합니다. 설명되지 않은 예외 자체가 위반 사항입니다.
seiso는 이러한 문서화 규칙에 초점을 맞춥니다. 문장이 기계가 작성한 것처럼 들리는지는 판단하지 않으며, 서식과 맞춤법은 다른 도구에 맡깁니다.
seiso 설치
지원되는 설치 방법 중 하나를 선택합니다. Rust, Python, npm 패키지는 동일한 명령줄 도구를 제공합니다.
cargo install seiso
uv tool install seiso
# 또는 pipx 사용:
pipx install seiso
npm install -g @scarletkc/seisoPyPI 및 npm 패키지에는 Apple silicon 및 Intel 기반 macOS, glibc를 사용하는 Linux x64 및 arm64, Windows x64용 사전 빌드 바이너리가 포함되어 있습니다. Alpine과 같은 musl 기반 Linux 배포판을 비롯한 기타 플랫폼에서는 Cargo로 설치합니다. 해당 플랫폼에서 Rust 툴체인을 사용할 수 있다면 PyPI 패키지를 소스에서 빌드할 수도 있습니다.
소스 체크아웃에서 작업하는 경우 Cargo를 통해 명령을 실행합니다.
cargo run -- <command>저장소 초기화
저장소 루트에서 seiso를 실행합니다. 먼저 초기 구성을 생성하도록 요청합니다.
seiso init이 명령은 저장소 루트에 seiso.toml 파일을 작성합니다. 생성된 구성에는 권장 제외 항목과 문서 종류 매핑이 포함됩니다. 초기 매핑은 프로젝트의 결정을 대신하는 것이 아니라 저장소를 위한 시작점이므로, 결과를 사용하기 전에 해당 제안을 검토해야 합니다.
첫 번째 검사 실행
생성된 구성을 검토한 후 저장소를 검사합니다.
seiso check기본적으로 seiso check는 안정화된 규칙만 실행합니다. 이러한 규칙은 seiso의 승격 기준을 충족했으며 프로젝트에 신뢰할 수 있는 기준선을 제공하도록 설계되었습니다.
진단 결과는 문제가 발생한 위치를 식별하고 해결 방법을 설명합니다. 따라서 많은 발견 사항은 명령의 출력만으로 바로 수정할 수 있습니다. 두 페이지 중 어느 페이지가 사실의 출처가 되어야 하는지 결정하는 것처럼 사람의 판단이 필요한 경우에는, 진단 결과가 내려야 할 결정을 명시합니다.
규칙과 문서 구조 살펴보기
규칙 명령을 사용하여 seiso가 검사할 수 있는 항목을 확인합니다.
seiso rule --all
seiso rule <CODE>seiso rule --all은 모든 규칙과 각 규칙의 상태를 나열합니다. seiso rule <CODE>를 사용하면 개별 규칙과 예시를 확인할 수 있습니다.
규칙을 실행하지 않고 seiso의 문서 모델을 살펴보려면 다음을 사용합니다.
seiso parse이 명령은 도구가 문서를 해석하는 방식을 배우거나 검사 결과가 특정하게 나온 이유를 조사할 때 유용합니다.
프리뷰 규칙은 신중하게 사용
아직 승격 기준을 충족하지 못한 규칙은 프리뷰로 제공됩니다. 프리뷰 규칙은 실험적이며 오탐을 보고할 수 있으므로 표준 검사에서는 활성화되지 않습니다.
--preview 옵션을 사용하여 로컬에서 실행해 볼 수 있습니다.
seiso check --preview프리뷰 규칙은 잠재적인 문서 문제를 조기에 찾는 데 유용하지만, README에서는 안정화될 때까지 CI 게이트에서 제외할 것을 권장합니다. 실용적인 작업 방식은 필수 검사에는 안정화된 규칙을 사용하고, 선택적인 로컬 검토에는 프리뷰 규칙을 사용하는 것입니다.
문서화 작업 흐름에 seiso 도입
- Cargo, uv, pipx 또는 npm을 사용하여 seiso를 설치합니다.
- 저장소 루트에서
seiso init을 실행합니다. seiso.toml에 있는 권장 제외 항목과 종류 매핑을 검토합니다.seiso check를 실행하고 보고된 발견 사항을 해결합니다.- 진단 결과를 이해해야 할 때
seiso rule --all과 개별 규칙 설명을 사용합니다. - 로컬에서
seiso check --preview를 실험하되, 프리뷰 결과를 CI 게이트로 사용하지 않습니다.
대규모 작업 흐름을 위해 seiso 문서에는 구성, 규칙 선택 및 출력 형식과 Claude Code 훅, pre-commit 및 CI 통합에 대한 안내가 포함되어 있습니다.
고급 안내
사실의 권위 있는 출처 유지
seiso가 정보의 중복이나 잘못된 위치를 보고하면 어떤 문서가 해당 사실을 소유해야 하는지 결정하세요. 표준 설명을 해당 문서로 옮기고 관련 페이지에서 그 문서로 연결하세요. 이렇게 하면 업데이트가 더 안전해지고 독자와 에이전트 모두 명확한 단일 진실의 원천을 확인할 수 있습니다.
문서 종류를 목적에 맞게 사용하기
절차 단계에는 howto를, 지속적으로 유효한 사실 정보에는 reference를, 설계 선택의 근거에는 adr을 사용하세요. 이러한 목적을 분리하면 한 페이지가 지침, 참조 데이터, 과거의 의사 결정이 뒤섞인 형태가 되는 것을 방지할 수 있습니다.
정당한 예외 기록하기
일부 저장소 결정에는 기계적인 규칙이 아니라 판단이 필요합니다. 예외를 유지하기로 했다면 그 이유를 문서화하세요. seiso는 설명이 없는 예외를 문서화 문제로 간주합니다. 미래의 기여자와 에이전트가 그것이 의도된 것인지 판단할 수 없기 때문입니다.
규칙이 불분명할 때 규약 참조하기
seiso 규약은 각 문서 종류의 계약과 진단에서 주장할 수 있는 근거를 정의합니다. 예상되는 구조를 파악하거나 발견된 문제를 어떻게 수정할지 결정해야 할 때는 seiso rule <CODE>의 출력과 함께 사용하세요.
결론
seiso는 프로젝트 문서에 공유된 구조와 집중적인 검증 도구를 제공합니다. seiso를 설치하고 seiso.toml을 생성 및 검토한 다음, 안정적인 검사를 실행하세요. 또한 규칙 설명을 활용해 사람과 코딩 에이전트가 문서를 더 쉽게 신뢰할 수 있도록 하세요. 프리뷰 규칙은 정식 승격 전까지 실험적인 것으로 취급하고, 소유권과 예외에 관한 결정을 저장소에 명시적으로 남기세요.