readme-sync

name	readme-sync
description	프로젝트를 분석하여 README.md를 생성하거나 최신 상태로 재작성합니다. README.md가 없으면 템플릿에 따라 새로 작성하고, 이미 있으면 현재 프로젝트 구조에 맞게 재작성합니다. README 작성, README 갱신, readme sync, 리드미 최신화 시 사용합니다.

개요

사람을 위한 README.md를 두 모드로 다룹니다.

• init: README가 없을 때 템플릿 기반으로 새로 작성합니다.
• update: README가 이미 있을 때 프로젝트 재분석 결과로 갱신합니다. 사용자 작성 콘텐츠는 보존합니다.

설계 원칙

• Simple is Best. 꼭 필요한 섹션만 두고, 각 섹션은 짧게 씁니다. 길면 사람들이 읽지 않습니다.
• 모드와 프로파일은 직교. --profile은 init의 기본값 프리셋이고 update에서는 무시합니다. "프로파일 때문에 기존 README가 망가졌다" 경로를 차단합니다.
• 말미 블록(라이선스·개인 저작물 고지)은 항상 옵션. 둘 다 비우는 것도 정상 경로입니다.

사용법

/readme-sync [--mode=init|update] [--profile=individual|business] [--force-license]

인자

인자	값	역할
--mode	init / update	동작 모드. 미지정 시 README.md 존재 여부로 추정.
--profile	individual / business	init 모드의 라이선스·고지 기본값 프리셋. update에서는 무시.
--force-license	(플래그)	기존 LICENSE 파일 덮어쓰기 허용. init 모드 + Q1=(a) 전용, 가드 통과 시에만 동작. 자세한 사양은 references/license.md 참고.

모드 선택 규칙

1. 인자가 명시되면 그대로 사용합니다.
2. 미지정이면 README.md 존재 여부로 추정합니다 (없으면 init, 있으면 update).
3. 추정과 사용자 의도가 어긋날 가능성이 있으면 1회 확인합니다.

프로파일 기본값 프리셋

프로파일	라이선스 표시 기본값	개인 저작물 고지 기본값
individual	사용자에게 (a)/(b) 중 선택을 요청	포함
business	(c) 표시하지 않음	미포함
(미지정)	두 질문을 그대로 제시	두 질문을 그대로 제시

프로파일은 기본값 프리셋일 뿐이며, 사용자는 개별 질문에서 다른 값을 자유롭게 선택할 수 있습니다.

---

init 모드

init-1단계: 프로젝트 분석

다음 정보를 수집합니다.

• 디렉토리 구조 (최대 깊이 2; 디렉토리 트리 정렬 규칙 적용)
• 프로젝트 성격 단서: package.json, pyproject.toml, Cargo.toml, .ai/AI-CONTEXT.md 등
• LICENSE 파일 존재 여부
• LICENSE-* 하이픈 패턴 비표준 파일 존재 여부 (헤더 파일 등; 발견 시 references/license.md의 "라이선스 헤더 파일명 가드" 참고)
• git config user.name, git config user.email로 Copyright 후보 추출

init-2단계: 대화형 질문

Q1. 라이선스 표시

README 말미에 라이선스 표시를 둘까요? (개인 작업이면 일반적으로 둡니다)
  (a) 오픈소스 라이선스 — Apache 2.0 / MIT 등. LICENSE 파일과 연결합니다.
  (b) 개인 저작물·비공개 표기 — 권장: All Rights Reserved
  (c) 표시하지 않음 — 회사 업무에서 흔한 선택입니다.

• --profile 기본값이 있으면 그 값을 하이라이트하고 확인만 받습니다.
• LICENSE 파일이 이미 있으면 (a)를 기본값으로 제시하고 라이선스 종류는 파일에서 자동 추정합니다.

Q1-1. (Q1=(a) 선택 시) 라이선스 종류

어떤 라이선스를 사용할까요?
  (1) Apache 2.0 — 특허 보호·NOTICE 보존 조항 포함. 본격 OSS 권장.
  (2) MIT — 가장 간결. 부가 파일 없음.

• 기존 LICENSE가 있고 종류가 추정되면 그 값을 기본값으로 제시합니다.

Q1-2. (Q1=(a) 선택 시) LICENSE 파일 생성

LICENSE 파일을 생성할까요? (README의 ./LICENSE 링크가 깨지지 않으려면 필요합니다)
  (생성 / 생성하지 않음)

• 기존 LICENSE 파일이 있으면 기본은 스킵입니다 — 이 질문 자체를 묻지 않습니다. 덮어쓰려면 --force-license 플래그를 명시합니다.
• 동작 세부 사항은 references/license.md의 "LICENSE 파일 생성 규칙"·"--force-license 플래그" 절을 따릅니다.

Q2. 개인 저작물 고지

README에 "개인 저작물 고지" 라인을 포함할까요?
  (포함 / 미포함)
  — 회사 업무라면 미포함이 일반적입니다.

• --profile 기본값이 있으면 그 값을 하이라이트하고 확인만 받습니다.

init-3단계: 템플릿 적용

templates/README-template.md를 읽어 다음 순서로 처리합니다.

1. 필수 섹션 채우기: Header / 개요 / Quick Start의 <자리표시자>를 프로젝트 분석 결과로 치환합니다.
2. 옵션 섹션 결정: 프로젝트에 필요한 <!-- optional:NAME --> 블록만 남기고 나머지는 통째로 삭제합니다.
   • optional:structure: 멀티 패키지/스킬 모음 등 디렉토리 트리가 가치 있을 때만.
   • optional:features: 스킬 목록·기능 목록 같은 핵심 자산이 있을 때만.
   • optional:docs: 외부 문서 또는 보조 문서 포인터가 필요할 때만.
   • optional:contributing: 공개 OSS인 경우에만.
3. 말미 블록 결정: Q1·Q2 응답으로 말미 블록 조합표에 따라 선택합니다.
   • optional:footer-license: Q1 (a)/(b)면 본문을 해당 분기 문구로 채우고, (c)면 블록 전체 삭제.
   • optional:footer-notice: Q2 포함이면 본문에 <작성자> 등을 채우고, 미포함이면 블록 전체 삭제.
   • optional:footer-copyright: 라이선스 또는 고지 중 하나라도 남으면 함께 두고, 둘 다 없으면 삭제. <YEAR>/<AUTHOR>/<EMAIL>은 git config·시스템 날짜로 채웁니다.
4. 마커·안내 주석 제거: 최종 결과물에서 <!-- optional:... --> 마커와 <!-- ... --> 안내 주석을 모두 제거합니다.

init-4단계: 검증·저장

1. LICENSE/NOTICE 파일 생성·처리: Q1=(a)일 때만 작동합니다. references/license.md를 읽고, Q1-2에서 "생성"을 골랐다면 "LICENSE 파일 생성 규칙"에 따라 LICENSE를 만들고 Apache 2.0이면 NOTICE도 함께 처리합니다. --force-license가 명시되어 있으면 "--force-license 플래그" 가드를 통과한 경우에만 기존 파일을 덮어씁니다.
2. 링크 무결성 점검: Q1=(a) 분기에서, 1단계가 끝난 시점에 LICENSE 파일이 디렉토리에 존재하는지로 판정합니다.
   • 존재함 — 1단계에서 새로 생성됐거나 기존 파일이 그대로 유지된 경우(동일 라이선스 스킵, --force-license 가드 스킵 포함). (./LICENSE) 링크가 살아있으므로 경고를 띄우지 않습니다.
   • 부재 — Q1-2에서 "생성하지 않음"을 골랐거나, 사용자가 생성·권유를 거부한 경우. (./LICENSE) 링크가 깨진 상태이므로 사용자에게 LICENSE 파일을 별도로 생성하도록 권유합니다.
3. README.md로 저장합니다. 기존 파일이 있으면 덮어쓸지 1회 확인합니다.

---

update 모드

기존 README.md를 보존하면서 프로젝트 변화를 반영합니다.

update-1단계: 기존 README 파싱

• 섹션 목록과 본문, 사용자 작성 콘텐츠를 식별합니다.
• 말미 블록의 라이선스·고지 유무·분기를 파악합니다.

update-2단계: 프로젝트 재분석

init-1단계와 동일하게 디렉토리 구조·스킬 목록·문서 등을 다시 모읍니다.

update-3단계: 갱신

• 사용자 작성 콘텐츠는 보존합니다. 자동 갱신 대상은 구조에서 파생되는 부분(디렉토리 트리, 스킬·기능 목록표 등)에 한정합니다.
• 말미 블록의 있음/없음·분기는 그대로 유지합니다. --profile이 들어와도 덮어쓰지 않습니다.
• 디렉토리 트리를 재생성·갱신할 때는 디렉토리 트리 정렬 규칙을 적용합니다. 기존 트리가 어긋나 있어도 사용자 작성 주석·코멘트는 줄 단위로 유지하면서 순서만 정렬합니다.

update-4단계: 저장

갱신된 README.md를 저장합니다. 사용자가 라이선스·고지 변경을 명시적으로 요청한 경우에만 init-2단계 질문 흐름을 호출합니다.

---

라이선스·개인 저작물 고지 옵션

LICENSE 파일 생성 규칙, --force-license 플래그 가드, 라이선스 헤더 파일명 가드의 세부 사양은 references/license.md에 분리되어 있으며, Q1=(a) 분기 진입 시 또는 LICENSE-* 비표준 파일 발견 시에만 읽습니다.

라이선스 표시 3분기

분기	권장 표기	동반 파일
(a) 오픈소스	Apache 2.0 / MIT 등 표준 라이선스 명 + LICENSE 링크	LICENSE, 필요 시 NOTICE, LICENSE_HEADER.txt 등 헤더 파일 (references/license.md의 명명 가드 참고)
(b) 개인 저작물·비공개	All Rights Reserved (권장) / UNLICENSED (npm 진영)	LICENSE 파일 없이 README에만 명시
(c) 표시하지 않음	—	없음 (회사 업무 관례)

• (b) 권장 표기 1순위는 All Rights Reserved. npm 패키지면 package.json의 "license": "UNLICENSED"와 맞춰 README에도 UNLICENSED를 쓰는 게 자연스럽습니다.
• (a) 분기에서는 사용자가 Q1-2에서 "생성"을 고른 경우 LICENSE 파일을 직접 생성합니다. 기존 LICENSE는 기본적으로 덮어쓰지 않으며, 덮어쓰기는 --force-license 플래그로만 허용됩니다.

개인 저작물 고지 토글

• 포함: ### 개인 저작물 고지 소섹션을 추가합니다. "이 프로젝트는 **<작성자>**의 개인 저작물입니다." 형식.
• 미포함: 회사 업무 컨텍스트 권장. 라이선스 분기와 독립적으로 토글됩니다.

말미 블록 조합표

Copyright 라인은 라이선스 또는 고지 중 하나라도 있으면 함께 둡니다. 둘 다 없으면 말미 블록 전체를 생략합니다.

라이선스	고지	말미 블록 구성
(a) 오픈소스	포함	## 라이선스 (OSS 문구 + LICENSE 링크) + ### 개인 저작물 고지 + Copyright
(a) 오픈소스	미포함	## 라이선스 (OSS 문구 + LICENSE 링크) + Copyright
(b) 비공개	포함	## 라이선스 (All Rights Reserved) + ### 개인 저작물 고지 + Copyright
(b) 비공개	미포함	## 라이선스 (All Rights Reserved 또는 UNLICENSED) + Copyright
(c) 없음	포함	### 개인 저작물 고지 + Copyright
(c) 없음	미포함	(말미 블록 전체 생략)

---

AI-CONTEXT.md와의 역할 분리

파일	독자	목적
README.md	사람	프로젝트 소개·사용법·라이선스
.ai/AI-CONTEXT.md	AI 에이전트	프로젝트 컨텍스트 라우터 (도메인·규칙·디렉토리 가이드)

README.md는 사람을 위한 진입점이고, .ai/AI-CONTEXT.md는 AI를 위한 진입점입니다. README는 AI-CONTEXT.md를 참고 자료로 활용할 수 있지만(예: 프로젝트 도메인 인용), 두 파일은 독립적으로 유지합니다.

.ai/AI-CONTEXT.md 생성·갱신은 ai-workspace 스킬이 담당합니다.

---

디렉토리 트리 정렬 규칙

## 디렉토리 구조 섹션의 트리(optional:structure 블록) 또는 본문 내 다른 트리 블록을 작성·갱신할 때 적용하는 규칙입니다. init 모드의 트리 작성과 update 모드의 트리 재생성 모두 이 규칙을 따릅니다.

• 같은 단계 내 정렬 기준: 대소문자를 무시한 알파벳순으로 정렬합니다.
• 디렉토리 우선: 디렉토리를 동일 단계의 파일보다 위에 둡니다.
• 숨김 항목 위치 고정 금지: .로 시작하는 항목(예: .ai/, .gitignore)도 같은 알파벳순 규칙으로 처리하며 별도 위치(맨 위/맨 아래)에 모아두지 않습니다.
• 결과: IntelliJ·VS Code 등 IDE의 기본 표시 순서와 일치합니다.

---

관련 skill

• ai-workspace: .ai/AI-CONTEXT.md 생성·갱신. README와 역할이 분리되어 있습니다.
• code-map: 소스코드 엔트리포인트·호출 흐름 색인. update 모드에서 디렉토리 구조 분석을 보조할 수 있습니다.