Communitygithub.com

shimo4228/readme-writer

Claude Code 스킬: 인간을 위한 README를 작성하고 개선합니다. 이 README는 인간, 검색, AI Overview를 위한 단일 정식 진입점입니다. llms-txt-writer의 인간용 대응 스킬입니다. 결정론적 구조 린트와 점수 없는 전체적 LLM 리뷰(AKC ADR-0008 Code-LLM Layering)를 수행합니다.

readme-writer란 무엇인가요?

이 스킬은 AI 에이전트(Claude Code 등)가 인간 중심의 README를 작성하고 개선할 수 있도록 설계되었습니다. `llms-txt-writer`가 AI 전용 표면을 담당하는 반면, 이 스킬은 **인간 표면의 단일 정식 진입점**을 담당합니다. 핵심 과제는 '인간에게 짧고 시각적으로' 전달하면서도, 'LLM이 README 하나만 읽어도 프로젝트를 복원할 수 있는 작은 정보 플로어'를 반드시 유지하는 두 가지 목표를 동시에 달성하는 것입니다. 이를 위해 결정론적 구조 린트(`readme_lint.py`)와 점수 없는 전체적 LLM 리뷰를 분리합니다. 구조적 속성(예: H1 개수, alt-text 유무)은 코드가 소유하고, 의미적 속성(예: 리드가 사람을 사로잡는지, README만으로 LLM이 복원 가능한지)은 LLM이 소유합니다. 또한, 시각적 요소는 Mermaid를 우선 사용하고, 래스터 이미지는 부하를 지탱하는 정보로 사용하지 않으며, 모든 이미지에 alt-text를 필수로 지정합니다. 이 스킬은 `when-code-when-llm`, `context-sync`, `jsonld-knowledge-graph` 등의 다른 스킬과 함께 사용되도록 설계되었습니다.

지원 대상✓Claude Code~Codex CLI✓Cursor✓Antigravity
npx skills add shimo4228/readme-writer

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

readme-writer — 인간을 위한 README 스킬

인간을 위한 README를 작성하고 개선하는 스킬입니다. llms-txt-writer가 AI 전용 표면을 담당하는 반면, 본 스킬은 인간 표면의 단일 정식 진입점을 담당합니다.

또한 중요한 사실: README는 grounding 경로(AI 검색/채팅에 repo URL을 붙여넣기)에서 LLM이 확실히 전제할 수 있는 유일한 표면입니다. 따라서 README는 '인간을 위해 짧고 시각적으로' 하면서도 'LLM이 README 하나만 읽어도 프로젝트를 복원할 수 있는 작은 정보 플로어'를 반드시 남겨야 합니다. 이 두 가지를 동시에 달성하는 것이 본 스킬의 핵심 과제입니다.

사용 시기

  • README.md / README.ja.md를 새로 만들거나 개선할 때
  • repo/프로젝트의 '인간이 처음으로 착지하는 페이지'를 정리할 때
  • 기존 README가 '기계에 치우쳐 인간에게 어중간'하거나 '인간용으로 너무 얇아 LLM이 파악하지 못하는' 상태를 수정할 때
  • README를 짧고 시각 우선으로 만들고 싶지만 정보 플로어를 떨어뜨리지 않으려 할 때

사용하지 않는 경우:

  • llms.txt / llms-full.txt / FAQ 등 AI 전용 문서 (→ llms-txt-writer)
  • 기사, 에세이, 블로그 등 긴 산문 (→ writing-ecosystem)
  • graph.jsonld 설계 (→ jsonld-knowledge-graph)

축은 '인간의 ATTENTION × LLM의 INFORMATION'

README 최적화의 진정한 대립 축은 '인간용 정보 vs LLM용 정보'가 아닙니다. **인간의 주의(짧고, 잡고, 스캔 가능) × LLM의 정보(README만으로 복원 가능)**입니다. 둘은 동일한 전략으로 수렴하므로(후술), 트레이드오프가 아니라 설계로 둘 다 잡습니다.

README는 확실히 읽히는 유일한 표면(하지만 '유일'은 아님)

  • AI 검색/인용 크롤러는 llms.txt를 사실상 읽지 않습니다(여러 2026년 로그 조사에서 대부분이 제로 요청, 주요 검색 벤더는 공식적으로 비대응을 표명).
  • graph.jsonld는 직접 fetch 시 plain text로 취급되며, README의 사실을 대체하지 못합니다(대조 실험).
  • 따라서 README에 놓은 정보를 '기계층이 백스톱한다'는 전제로 얇게 만들어서는 안 됩니다.

단, 중요한 교정: 'LLM은 README 만 읽는다'는 너무 강한 주장입니다. 정확히는 '일반적인 URL 붙여넣기/검색 grounding에서는 README가 확실히 전제할 수 있는 유일한 표면'입니다. 다른 경로(검색 인덱스가 다른 파일을 이미 청크화함 / README의 링크 추적 / GitHub connector 및 API를 통한 파일 트리 노출 / 사전 학습 지식)도 존재합니다. 결론이 가장 강력한 것은 익명 라이브 웹 grounding과 직접 랜딩 fetch입니다. 반대로 라우팅된 코딩 에이전트(Claude Code / Cursor 등)는 llms.txt를 on-demand로 읽으므로, llms.txt는 agentic 채널의 보험으로 여전히 유효합니다. 단, AI 검색의 진입점은 아닙니다.


왜 '구조 린트'와 '전체적 리뷰'를 분리하는가

README 품질에는 두 종류의 속성이 혼재합니다. Code-LLM Layering(구조는 code가 100% 정확도로 소유, 의미는 LLM이 소유)에 따라 소유자를 분리합니다. 판단 축은 when-code-when-llm을 참고: '동일한 바이트열이 문맥에 따라 다른 의미를 가질 수 있는가?'

속성예시종류소유자
구조적H1 개수 / 헤딩 레벨 / alt-text 유무 / 로컬 링크 해결 / 래스터 그림 파일명 / 배지 개수 / details 내 DOI 등 / H1 직후 산문 줄structuralcode(readme_lint.py)
의미적lead가 사람을 사로잡는가 / 가치 제안의 명확성 / README만으로 LLM이 복원 가능한가 / 이야기 흐름 / 배지가 허영인가semanticLLM의 전체적 리뷰

README에 연구 기반 수치 점수는 만들지 않습니다. llms.txt의 섹션 비율(ski-ramp 등)은 LLM 인용 연구에서 검증된 결정론적 신호이지만, README의 '좋은 진입점인가'는 의미적 판단이며 동등한 결정론적 지식이 없습니다. Entity density 등의 AI 표면 지표를 인간 README에 가져오는 것은 안티패턴입니다.

하지만 '구조적 AI 가독성'은 적극 채용합니다(two-sided rule)

'AI 표면 지표를 가져오지 않는다'는 절반만 맞습니다. 원칙은 **'아이디어가 어떻게 전달되는가는 최적화해도 좋다(강도에 상한 없음). 아이디어가 무엇인가는 절대 왜곡하지 않는다'**입니다.

  • 채용(강도 무제한): 헤딩 계층, 정보 설계, entity anchoring(저자명/ORCID/DOI/표준 식별자를 산문에 작성), 고유/조어 어휘의 anchoring, answer-first lead, 한눈에 보는 표. 이는 인간과 grounding 경로의 LLM 모두에 효과적인 수렴 영역입니다.
  • 금지: keyword stuffing, 부풀리기 속성, 질문 헤딩 농사(farming), glossary 투하, 검색 보상 함수에 맞춘 주장 왜곡. 인용이나 스타는 성공 지표가 아니므로, 왜곡이 봉사할 목표 자체가 없습니다.

최소 LLM-read 플로어(작고, 협상 불가, 비대화 금지)

규칙: README를 LLM이 그것 한 장만 읽었다고 가정했을 때(llms.txt도 graph도 읽히지 않음), 텍스트만으로 프로젝트를 복원할 수 있어야 합니다.

플로어 요소(산문 / markdown / Mermaid로, 이미지만 / details 내만 / 링크 대상만은 불가):

  1. identity 문장(처음 1-2문장, 단독으로 읽힘): 'X는 {누구}를 위해 {무엇을} 하는 {카테고리}이다'
  2. 해결하는 문제 / 대상 / 차별화 포인트
  3. 정식 사실: 실명, 언어/stack/상태. 연구/DOI repo의 경우 DOI + 인용 방법(BibTeX / CITATION) + 어휘를 뒷받침하는 3-6개 핵심 개념 정의
  4. 구체적 예시 하나만: 코드라면 함수 signature + 최소 실행 조각(전체 구현은 게재하지 않음——비대화 + 환각 유발) / 연구라면 핵심 주장 + 2-3개 핵심 숫자
  5. 심층 문서로의 링크 맵은 포인터만. 부하를 지탱하는 사실을 링크 대상 / llms.txt / graph에만 두지 않음

가장 중요한 함정: 플로어는 작은 협상 불가 코어입니다. '자르지 말고 재구조화하라'를 너무 강하게 적용하면, Mermaid / details / 플로어 절에 정보가 보존되어 README가 위장 llms-full.txt로 비대화됩니다. 인간의 목표는 짧게였습니다. 플로어 외에는 가차 없이 자르거나 relocate합니다(→ length budget).

graph.jsonld / llms.txt를 README에서 만들 때는, README 산문을 구조 소스로 사용하지 않습니다. 식별자, graph edge는 CITATION.cff / .zenodo.json / frontmatter의 작은 manifest에서 derive합니다(수동 병렬 복사는 드리프트 발생).

GitHub의 메타 표면(repo description / topics / social-preview / CITATION 파일 / release / package metadata)도 grounding에 효과적인 floor의 일부입니다. README 본문에서는 설정하지 않지만(gh repo edit / release-doi 측), 체크리스트로 갖추어졌는지 확인합니다.


Visual-first(Mermaid 우선, raster 마지막)

'짧고 시각적으로'의 올바른 해석은 **'산문의 벽을 스캔 가능한 구조로 압축한다'**입니다. 산문을 이미지화하는 것이 아닙니다. 그리고 'Mermaid 우선' ≠ '모든 것을 Mermaid로'——먼저 그림으로 만들 가치가 있는지를 선별합니다. 모바일(좁은 폭)에서 무너지지 않고, LLM이 읽을 수 있는 형식을 선택합니다.

형식 선택

내용최적 형식이유
3단계 선형 / 단순 열거산문 / 리스트 / 작은 표모든 디바이스(특히 모바일)에서 읽을 수 있음. 그림으로 만들 가치 없음
진정한 그래프 형태(관계, 다중 분기, matrix)Mermaid(TD 세로 방향)소스가 텍스트여서 LLM도 읽을 수 있음. 세로 스크롤은 모바일에서 자연스럽고, 가로(LR)는 무너짐
크고/복잡한 그림committed SVG(확대/이동 가능) / 서브시스템 분할거대 Mermaid는 데스크탑에서도 한계에 도달하고 모바일에서 무너짐
실제 UI / 실행 결과 / 사진raster(PNG/JPG/WebP/GIF)Mermaid로 표현할 수 없는 것만

모든 그림에는 한 문장의 텍스트 등가물을 반드시 첨부합니다(하드 규칙). 이것이 '인간과 LLM 모두에게 전달됨'을 보장하는 본체입니다: 모바일에서 그림이 무너진 인간, ```mermaid fence를 불투명 코드로 건너뛰는 LLM 추출기, 스크린 리더를 동시에 구합니다. 그림은 그 위의 시각적 보너스일 뿐, 정보의 유일한 전달자가 아닙니다.

Mermaid 요점

  • GitHub가 theme-aware SVG로 네이티브 렌더링. 소스는 텍스트(diff 가능, ~10 token/edge)이며 pixel을 볼 수 없는 텍스트 전용 크롤러도 읽을 수 있습니다. 산문/그래프에 묻힌 구조(concept matrix, phase binding, pipeline 단계)를 Mermaid로 만들면 짧아지고 정보 밀도가 높아집니다.
  • 모바일 최우선으로 TD(세로). 가로 LR은 좁은 폭에서 깨지기 쉽습니다.
  • 렌더링 상한은 char 기준(maxTextSize 기본 50,000) + edge 기준이며, 노드 수가 아닙니다('50-100 node가 한계'는 속설). 초과할 것 같으면 서브시스템 분할. 특수한 Project README에서는 렌더링되지 않습니다.
  • 추출기가 Mermaid를 떨어뜨릴 가능성이 있으므로, 위의 텍스트 등가물로 의미를 반드시 별도로 보장합니다.

raster / 기타

  • raster는 부하를 지탱하는 정보를 맡기지 않습니다. alt-text를 필수(하드 플로어: 텍스트 경로는 alt만 읽음 = alt 없는 이미지는 LLM에 비가시. a11y만의 이야기가 아님).
  • dark/light는 <picture><source media="(prefers-color-scheme: …)"><img alt="…"></picture>. <img alt>는 이중으로 부하를 지탱.
  • 이미지 asset은 repo에 commit하여 상대 경로로 참조. 외부 hotlink(camo 파손)와 인라인/애니메이션 <svg>/<embed>/<object>(GitHub가 sanitize)를 피함.
  • badge는 2-4개의 고신호만(CI / version / license / 연구 repo는 DOI). Vanity badge를 피함. 좁은 폭에서 badge 줄이 너무 쌓이지 않도록 개수 제한.
  • CLI repo: asciinema→agg GIF + 한 문장 캡션. UI repo: 스크린샷/GIF + alt-text.

드문 bespoke 그림은 Claude Artifacts / Claude Code의 svg・diagram skill로 committable한 SVG를 생성하여 assets/에 배치.


Length budget(어수 목표 없음)

어수 목표는 두지 않습니다('500-1500어의 sweet spot', 'visual README는 star가 증가한다(GitHub 연구)'는 모두 날조/무출처로 기각됨). 대신:

  • above-the-fold(첫 1화면 = 30초 안에 '자신에게 맞는지' 판단): 임의의 hero → H1 → 한 줄 tagline(가치 제안 = LLM이 가장 확실히 추출하는 줄) → ≤4 functional badge → 플로어 사실 → copy-paste quick start. 깊은 근거는 이 후.
  • 순서는 repo 종류에 따라 변경: 'quickstart→rationale'는 소프트웨어용. 논문 / dataset / 개념 / DOI essay repo에서는 해당하지 않음. 고정 순서를 강제하지 않고, **'identity + canonical facts가 deep rationale보다 앞'**만 지킴. lint의 identity_lead는 'lead 문장의 존재'만 구조적으로 보고 순서는 강제하지 않음.
  • 총량은 1변수로 결정: 정식 문서 사이트 / ADR이 심층을 흡수하는가. 깊은 '왜' / 설계 근거는 ADR / docs/ / llms-full.txt / 등록 논문으로 옮기고, README에는 한 줄 포인터(Diátaxis의 explanation-displacement). 이것이 '450줄 연구 repo README'의 직접적인 치료.
  • <details>는 이차적인 벌크만(option 표 / FAQ / troubleshooting / 전체 glossary). 인간의 시야를 정리하면서 LLM에는 전달됨. 단, 플로어를 넣지 않음(primacy 상실 + Ctrl+F 불가. raw-markdown 경로에서는 읽히지만, 렌더링 페이지의 요약기는 접힘을 de-prioritize할 가능성 있음).

Workflow(Code filter → LLM review → 인간 gate)

1. Code filter — readme_lint.py(결정론적, structural only)

uv run --directory ~/.claude/skills/readme-writer python -m scripts.readme_lint "$ARGUMENTS"

인자는 README의 절대 경로. --json으로 기계 가독 출력. exit code가 code-owned gate(0=clean 또는 warning만 / 1=error severity 있음 / 2=not found・too large).

검사 항목(점수가 아닌 구체 issue. severity 2단계):

error(gate를 떨어뜨림, 하드 구조)

  • single_h1 — H1은 정확히 1개
  • heading_levels — 헤딩 레벨을 건너뛰지 않음
  • alt_text — 모든 이미지에 alt(하드 플로어: alt 없음 = LLM에 비가시)
  • local_link — 로컬 상대 링크 / 이미지 src가 실제 존재

warning(조언, gate를 떨어뜨리지 않음) — 구조적으로 감지하지만 '진짜 문제인가'는 판단이므로 표면만. 의미 판단은 LLM review에 위임:

  • raster_diagram_hint — 그림 같은 파일명의 raster(architecture/flow/diagram/pipeline 등의 .png/.jpg/.webp/.gif) → Mermaid화 제안. SVG, 스크린샷, 로고는 제외
  • badge_budget — badge가 너무 많음(기본 >6). 개수만 판단(vanity 여부는 LLM)
  • details_floor_leak — <details> 내에 DOI / BibTeX / CITATION 토큰(floor 누출 징후. '진정한 floor인가'는 LLM 판단)
  • identity_lead — H1과 첫 번째 section 사이에 산문 lead 문장 없음(순서는 강제하지 않음. H1 부재는 single_h1이 담당)
  • doi_citation_pairing — DOI가 있는데 인용 방법(Citation 절 / BibTeX / CITATION.cff)이 없음(DOI를 비연구 repo에 강제하지 않음——DOI가 있을 때만 발화)

2. LLM holistic review(rubric-as-lens, 점수 없음, signal-first)

lint가 통과하면 Claude가 README를 전체적으로 읽고, 다음 lens로 구체 소견 + 구체 diff를 제시:

  • 🚩 README-only recovery(기함, 최고 레버리지) — README의 텍스트만 읽고 (identity / 대상자 / 문제 / 차별화 포인트 / 해당 시 DOI・인용 / 3-6개 core concept / 예 1개 / 다음 링크)를 복원 가능한가 확인. 누락을 구체적으로 열거('대상자가 쓰여 있지 않음' 등). 점수는 붙이지 않음. 이것은 '최소 LLM-read 플로어'의 운영화 그 자체.
  • Lead의 What / Who / Why — 첫 화면에서 '무엇을, 누구를 위해, 왜 신경 써야 하는지'를 알 수 있는가
  • 인간 훅 / 가치 제안 — 추상어가 아닌 구체로 가치를 말하고 있는가
  • 이야기 / 스캔 가능성 — 단락, 헤딩, 리스트, Mermaid가 인간에게 따라가기 쉬운가
  • 짧음 검증(가장 중요한 역방향 체크) — 플로어 외가 relocate되었는가. Mermaid / details / 플로어에 정보를 보존하여 위장 llms-full.txt로 비대화되지 않았는가
  • visual 적절성 — 그림은 Mermaid인가(raster라면 Mermaid화 / 텍스트 등가물이 있는가). badge는 고신호인가(vanity가 아닌가)
  • fact 일치 — 주장이 기계층(llms.txt / graph.jsonld)과 모순되지 않는가 → context-sync에 위임

점수를 붙이지 않는 이유(signal-first + scaffold-dissolution): '다음 행동을 바꾸는 정보'만 제시. Lead: 6/10은 행동을 바꾸지 않음. 'lead가 누구를 위한 것인지 말하지 않음'이 행동을 바꿈. 출력은 diff 형식으로 y/n 승인 가능한 세분도로 분할. author-reviewer separation을 위해 리뷰는 구현자와 다른 agent 프로세스로 돌리는 것이 바람직함(editor / essay-reviewer와 동형).

3. fact 일치 확인 → context-sync

README의 사실이 llms.txt / llms-full.txt / graph.jsonld와 일치하는지(cloaking 회피)는 context-sync가 정본. 본 스킬에서는 재구현하지 않음.

4. 인간 gate

diff를 인간이 승인하여 적용.


이 스킬이 하지 않는 일(경계)

  • llms.txt / llms-full.txt를 쓰지 않음(→ llms-txt-writer)
  • graph.jsonld를 설계하지 않음(→ jsonld-knowledge-graph)
  • cross-surface 드리프트 감지/동기화를 하지 않음(→ context-sync / release-doi)
  • 기사/에세이를 편집하지 않음(→ writing-ecosystem)
  • repo의 description / topics / social-preview를 설정하지 않음(gh repo edit / release-doi 측. 본 스킬은 체크리스트로 제시할 뿐)
  • 품질 점수 / grade / 평점을 내지 않음

안티패턴

  • 수치 점수만 내고 구체안 없이 끝남(recommender형 함정)
  • 구조 lint로 끝낼 수 있는 항목을 LLM에게 판단시키거나, 의미적 판단을 regex로 대체함(when-code-when-llm 참고)
  • AI 표면의 수치 지표(ski-ramp / entity density / 질문 헤딩 농사)를 인간 README에 유용함(가독성 저하)
  • '비주얼 우선'을 산문의 이미지화로 해석함(raster 그림은 텍스트 전용 LLM에 비가시 = 정보를 에이전트로부터 숨김. Mermaid를 사용)
  • '자르지 말고 재구조화하라'를 너무 강하게 적용하여 위장 llms-full.txt화함(플로어는 작게, 위는 가차 없이 자르거나 relocate)
  • 기계층(llms.txt/graph)이 백스톱한다는 전제로 README 플로어를 얇게 함(grounding 경로에서 읽히지 않음)
  • llms.txt/graph를 README 산문으로부터 derive함(드리프트. manifest에서 derive)
  • 인간을 위해 사실을 부풀리거나 수익화 어필을 추가함(진정성 훼손 + 기계층과의 모순 = cloaking. 포장은 바꿔도 주장은 바꾸지 않음)

Verification

cd ~/.claude/skills/readme-writer
uv sync --dev
uv run pytest tests/ --cov=scripts --cov-report=term-missing

fixtures/sample_clean.md(issue 0, Mermaid 그림을 사용하는 best-practice 예)와 fixtures/sample_issues.md(전 9개 체크를 발화시키는 예)로 기본 동작을 확인할 수 있습니다.


Related

  • llms-txt-writer — AI 표면의 쌍이 되는 writer(연구 기반 geo_check.py 보유). 본 스킬은 인간 표면.
  • when-code-when-llm — structural / semantic의 판단 축
  • context-sync — README ↔ 기계층의 fact 일치 / 드리프트(fact 검증은 이쪽에 위임)
  • jsonld-knowledge-graph — graph.jsonld 설계
  • writing-ecosystem — 인간용 장문 산문의 orchestrator
  • inspiration.md — 설계의 출처, 1차 연구의 provenance, 외부 증거의 출처(Portability를 위해 SKILL.md 본문에서 분리)

관련 스킬