0x0w1/jig

README

이 스킬을 사용하여 저장소의 실제 상태를 기반으로 README.md를 생성하거나 업데이트합니다.

절차

1. 저장소를 스캔합니다:
   • 매니페스트 및 빌드 파일: pyproject.toml, package.json, Cargo.toml, go.mod, Makefile, 잠금 파일.
   • 진입점, CLI 인자 정의, 스크립트, 서비스 설정 (Dockerfile, docker-compose*.yml).
   • docs/ 아래의 기존 문서와 코드 내 사용 예제.
2. 프로젝트 유형을 분류합니다: CLI 도구, 라이브러리, 서비스/앱, 기타. 유형은 아래 프로필이 설정되지 않았을 때 사용할 섹션 레이아웃을 결정합니다.
3. 아래 프로필 컨트랙트에 따라 README 프로필을 결정합니다. 결정된 프로필은 이 저장소의 일반 기본값을 대체합니다. 아무것도 결정되지 않으면 하나를 제안하고 그대로 진행합니다.
4. 현재 상태에 따라 분기합니다:
   • README.md 없음 → 생성 경로: 아래 섹션 레이아웃으로 README를 작성합니다.
   • README.md 있음 → 업데이트 경로: README의 모든 검증 가능한 주장(명령어, 옵션, 파일 경로, 링크, 기능 설명)을 저장소와 대조합니다. 불일치 항목을 드리프트 리스트로 모아 보고한 후 수정을 적용합니다. 여전히 정확한 섹션은 그대로 둡니다.
5. 모든 작성 줄에 정확성 규칙을 적용합니다.
6. 아래 압축 규칙에 따라 압축 패스를 실행합니다:
   • 생성 경로: 작성하면서 압축 규칙을 적용합니다. 아직 게시된 것이 없으므로 제안할 것도 없습니다.
   • 업데이트 경로: 중복과 과장 주장을 제안서로 모읍니다. 각 사실이 어디에 반복되었고 어떤 세부 문서로 옮길지 이름을 지정한 후, 이동 전에 물어봅니다. 사용자가 거절하더라도 제안서는 보고합니다.
7. 변경 사항을 병합합니다:
   • 저장소에 develop-task-flow 스킬(또는 설치된 jig-develop-task-flow)이 있을 경우 해당 스킬을 따릅니다: chore/<슬러그> 브랜치, docs: 커밋으로 스쿼시 병합, 이후 develop 푸시.
   • 그렇지 않으면 현재 브랜치에 일반 커밋을 제안합니다.

프로필 컨트랙트

같은 프로젝트 유형의 두 저장소라도 README를 다르게 작성합니다. 하나는 번역 미러를 유지하고, 다른 하나는 설치를 가이드로 옮기며, 세 번째는 기여자들이 이미 따르는 표 규칙을 가집니다. 이는 결정 사항이지 저장소를 스캔하여 알 수 있는 사실이 아니므로, 한 번 기록하고 이후 실행마다 읽어옵니다.

프로필을 다음 순서로 결정합니다:

1. JIG_README_PROFILE 환경 변수.
2. git config --local --get jig.readmeProfile.
3. .jig/readme.md.

프로필이 결정되면 해당 저장소의 섹션 레이아웃 및 언어 규칙을 재정의합니다. 프로필이 언급하지 않은 내용은 기본값으로 돌아갑니다. 프로필을 읽고 따르며 보고서에 이름을 명시합니다.

아무것도 결정되지 않으면 스캔 결과에서 하나를 작성하여 제안합니다: 분류된 유형, 저장소가 이미 사용하는 언어, 미러 존재 여부, 현재 README가 암시하는 섹션 순서, 이미 오버플로우를 보유한 세부 문서. .jig/readme.md는 사용자가 수락한 후에만 작성합니다. 사용자가 거절하거나 응답하지 않으면 일반 기본값으로 계속 진행하고 그렇게 말합니다. 프로필이 없는 것은 정상 상태이지 차단 요소가 아닙니다.

파일은 결정 사항만 기록합니다. 임계값이나 체크리스트를 포함하지 않습니다. README 품질은 저장소를 앞에 두고 이 스킬이 내리는 판단에 맡깁니다.

# README 프로필

> 기준: <결정 방식>, <YYYY-MM-DD>

## 언어

정식: `README.md` (영어). 미러: `README.ko.md` (한국어), 동일 작업에서 업데이트.

## 섹션

제목 및 링크 행, 이게 무엇인지, 빠른 시작, 스킬, 문서, 라이선스.

## 세부 문서

설치 옵션 → `docs/installation.md`. 로드맵 및 설계 기록 → `docs/roadmap.md`, 문서 홈에서만 링크.

## 규칙

식별자 표는 설명 셀을 한 절로 유지합니다. 기여자 명령은 `<details>` 블록 안에 넣습니다.

섹션 제목이 계약이며, 그 아래의 문단은 저장소 고유의 내용입니다. 이 제목들이 존재하기 전에 작성된 프로필도 이를 사용한다면 올바르게 읽힙니다.

섹션 레이아웃

필수 섹션, 순서대로:

1. 제목 및 한 줄 설명.
2. 소개: 프로젝트가 하는 일과 존재 이유.
3. 설치.
4. 사용법.

프로젝트 유형별 추가:

• CLI 도구: 명령어와 옵션 표.
• 라이브러리: 예제 코드가 있는 API 요약.
• 서비스/앱: 실행 방법(개발 및 프로덕션)과 필요한 환경 변수.

선택 사항: 문서 링크, 라이선스.

레이아웃 규칙

• 사람들이 복사하는 식별자(스킬 이름, 명령어, 옵션, 경로)에는 표가 적합합니다. 이러한 이름을 망가뜨리는 것은 열 간 너비 비율입니다. GitHub는 내용에 따라 열 크기를 조정하므로, 식별자 열보다 몇 배 긴 설명 열이 식별자를 압축하여 이름 중간에서 줄바꿈되게 하여 존재하지 않는 이름을 보여줍니다.
• 설명 셀은 식별자와 거의 같은 길이, 약 한 절로 유지합니다. 설명이 길어지면 줄이거나 전체를 목록으로 변경합니다: - **\이름`** — 설명`.
• 설명 내 줄바꿈은 예상되며 추가 작업이 필요하지 않습니다.

압축 규칙

README는 독자가 프로젝트 사용을 결정하기 전에 읽힙니다. README의 모든 내용은 그 관심을 위해 경쟁하므로, 길이는 증상입니다: 긴 README는 거의 항상 여러 곳에 작성된 하나의 사실이지, 할 말이 많은 하나의 프로젝트가 아닙니다.

이동하고, 삭제하지 마십시오. 같은 사실이 두 곳 이상에 나타나면 독자가 먼저 도착하는 한 곳에 유지하고 나머지를 해당 사실을 이미 다루는 세부 문서로 이동하며, 해당 문서가 없으면 생성합니다. 아무것도 손실되지 않습니다. README가 반복을 멈춥니다. 맞아야 할 줄 수는 없습니다. 진정으로 필요한 API 예제가 있는 라이브러리 README는 너무 길지 않으며, 같은 말을 두 번 하는 짧은 README도 여전히 잘못되었습니다.

독자가 얻는 것으로 시작하십시오. 소개는 어떤 기능이 존재하는지가 아니라 무엇이 더 쉬워지는지 말합니다. 병합 시 등급이 매겨진 릴리스 트레일러를 기록합니다는 기능이고, 버전이 마이너였던 이유를 재구성하지 않아도 됩니다는 독자가 얻는 것입니다. 증거가 가장 강한 순서대로 주장을 정렬하고, 주변 문단도 같은 순서로 나열합니다. 문단과 불릿이 다른 우선순위를 암시해서는 안 됩니다.

저장소가 뒷받침할 수 있는 주장만 하고, 적용되는 조건을 명시하십시오. 저장소가 입증할 수 없는 주장은 누그러뜨리지 말고 생략합니다. 가치가 나타나는 조건을 명시하여, 해당 조건 밖의 독자가 나중에 발견하기보다 빠르게 프로젝트를 배제할 수 있게 합니다.

설치 전에 읽지 않는 내용은 자릅니다. 로드맵, 설계 기록, 방향 노트는 프로젝트가 자체적으로 보관하는 것입니다. README가 아닌 문서 홈에서 링크하십시오.

기여자 자료를 접으십시오. 빌드, 재생성, 검증 명령어는 이미 저장소를 클론한 사람들을 위한 것입니다. <details> 블록이나 기여 문서에 넣습니다.

하나의 값만 다른 블록은 병합하십시오. 플랫폼이나 대상별로 인수만 다른 별도의 명령어 블록은 해당 인수를 명명한 하나의 블록이 됩니다.

독자에게 최상단을 넘어가는 방법을 제공하십시오. README에 약 4개 이상의 섹션이 있으면 제목 아래에 한 줄 링크 행을 배치하여 돌아오는 독자가 원하는 섹션으로 바로 이동할 수 있게 합니다.

정확성 규칙

• 저장소와 확인된 설치 및 실행 명령어만 작성합니다. 스크립트, 매니페스트 또는 잠금 파일이 이를 보여주어야 합니다.
• 링크된 모든 파일 경로가 존재하는지 확인합니다.
• 저장소에 포함되지 않은 기능, 배지, 통합을 설명하지 않습니다.
• 주장을 확인할 수 없으면 생략하고 대신 보고합니다.

안전 규칙

• .jig/readme.md는 사용자가 제안을 수락한 후에만 작성되며, 일반 README 업데이트의 부작용으로 작성되지 않습니다.
• 기존 .jig/readme.md는 명시적 확인 없이 덮어쓰지 않습니다. 변경 사항을 제안하고 대체하는 내용을 명명합니다.
• .jig/ 아래의 다른 것은 건드리지 않습니다. version-rubric은 .jig/versioning.md를 소유합니다.
• 게시된 README는 조용히 재구성되지 않습니다. 압축 패스는 제안하고 기다립니다.
• 관련 없는 사용자 변경 사항은 보존합니다.

언어 규칙

• 기존 README는 해당 언어를 유지합니다.
• 새 README는 저장소가 문서에 이미 사용하는 언어로 작성되며, 기본값은 영어입니다. 기술 용어는 백틱으로 표시합니다.
• 사용자의 명시적 언어 요청이 둘 다를 재정의합니다.

보고서

• 프로젝트 유형과 취해진 경로(생성 또는 업데이트).
• README 프로필: 경로 및 출처, 또는 제안 및 거절, 또는 없음 및 일반 기본값으로 실행 중.
• 업데이트 경로의 경우: 드리프트 목록과 수정된 내용.
• 압축 제안서: 두 곳 이상에서 반복된 각 사실, 이동할 위치, 사용자 수락 여부.
• 확인할 수 없어 생략된 주장.