toki/alt

toki 5c79ca171e initial: project scaffold with agent-ops, cli, client, services, packages

2026-05-24 21:23:30 +09:00

6.7 KiB

Raw Blame History

name	version	description
create-readme	1.0.0	README 작성, README 생성, 프로젝트 설명 문서 작성 요청에 대해 사람이 읽기 쉽고 AI가 다음 작업에 바로 활용할 수 있는 표준형 README.md를 생성하는 공통 스킬

README 생성

목적

프로젝트 루트의 README.md를 표준형으로 작성한다. README는 사람에게 프로젝트의 목적과 사용법을 설명하면서, AI 에이전트가 다음 작업에서 빠르게 맥락을 파악하고 실행할 수 있는 작업 안내 문서가 되도록 구성한다.

언제 호출할지

사용자가 "README 작성해줘", "README 만들어줘", "프로젝트 설명 문서 만들어줘"라고 요청할 때
프로젝트 루트에 README.md가 없거나 내용이 비어 있을 때
기존 README가 제품 설명, 실행 방법, 구조, 검증 명령을 충분히 담지 못해 초기 정리가 필요할 때
AI 에이전트가 프로젝트를 이어서 작업할 수 있도록 핵심 맥락을 한 문서에 모아야 할 때

입력

project-name: README에 사용할 프로젝트 이름 (선택, 없으면 repo 이름 또는 package metadata에서 추론)
audience: 주요 독자 또는 사용자 (선택)
purpose: 프로젝트 목적 한 줄 요약 (선택)
scope: README에 포함할 범위 또는 제외할 범위 (선택)
overwrite: 기존 README 덮어쓰기 허용 여부 (선택, 명시 없으면 덮어쓰지 않음)

README 표준 구성

README는 프로젝트 특성에 맞게 필요한 섹션만 사용하되, 기본 순서는 아래를 따른다.

# <project-name>

<프로젝트 목적 1~3문장>

## 현재 상태

<개발 단계, 사용 가능 범위, 중요한 제약>

## 빠른 시작

<설치, 실행, 테스트의 최소 명령>

## 주요 명령

| 목적 | 명령 | 비고 |
|------|------|------|

## 구조

| 경로 | 역할 |
|------|------|

## 작업 맥락

<AI가 다음 작업에서 먼저 알아야 할 규칙, 문서, 로드맵, 주요 경계>

## 개발 흐름

<브랜치, 테스트, 검증, 리뷰 또는 배포 흐름>

## 환경 변수

| 이름 | 설명 | 필수 |
|------|------|------|

## 참고 문서

- <관련 문서 경로>

AI-first 작성 기준

README 상단에는 프로젝트가 무엇을 해결하는지와 현재 사용할 수 있는 범위를 먼저 쓴다.
AI가 작업을 이어받을 때 필요한 경로, 명령, 검증 방법, 주요 문서를 명확한 제목과 표로 정리한다.
agent-ops/가 있으면 규칙, 로드맵, 스킬 문서를 참고 문서나 작업 맥락에 연결한다.
agent-ops/roadmap/current.md가 있으면 README에 현재 작업 위치를 복사하지 말고, 로드맵을 확인할 문서 경로만 적는다.
README는 제품 소개 문서이면서 작업 진입점이다. 마케팅 문구보다 실행 가능한 정보와 프로젝트 경계를 우선한다.
불확실한 내용은 단정하지 않고 TODO 또는 "확인 필요"로 남긴다.

먼저 확인할 것

루트 README.md 존재 여부와 기존 내용 확인
package.json, pyproject.toml, Cargo.toml, go.mod, Makefile, docker-compose.yml 등 실행/검증 명령 근거 확인
agent-ops/rules/project/rules.md가 있으면 프로젝트 개요, 기술 스택, 도메인 매핑 확인
agent-ops/roadmap/ROADMAP.md 또는 agent-ops/roadmap/current.md가 있으면 제품 방향과 활성 Milestone 문서 경로만 확인
주요 소스 디렉터리와 테스트 디렉터리를 rg --files로 가볍게 확인

실행 절차

기존 README 처리 결정
- README.md가 없으면 새로 생성한다.
- README.md가 있고 사용자가 덮어쓰기를 명시하지 않았으면 기존 내용을 보존하고, 필요한 섹션만 보완한다.
- 기존 README의 제품 설명, 설치/실행 명령, 경고, 라이선스, 배포 정보를 삭제하지 않는다.
프로젝트 근거 수집
- metadata 파일에서 프로젝트 이름, 설명, scripts, dependencies, runtime을 확인한다.
- Makefile, compose 파일, CI 설정, 테스트 설정에서 실행 명령과 검증 명령을 확인한다.
- 소스 구조는 전체 정독하지 않고 README 작성에 필요한 상위 경로와 대표 진입점만 확인한다.
- 명령을 추론해야 하면 "추정"으로 쓰지 말고 TODO로 남긴다.
README 초안 작성
- 표준 구성 순서를 기준으로 프로젝트에 맞는 섹션을 선택한다.
- 빠른 시작에는 최소 실행 경로를 짧게 쓴다.
- 주요 명령 표에는 실제로 확인한 명령만 넣는다.
- 구조 표에는 AI가 작업 범위를 잡는 데 도움이 되는 경로만 넣는다.
- 작업 맥락에는 agent-ops 문서, 로드맵, 도메인 규칙, 중요한 작업 경계를 연결한다.
기존 내용 병합
- 기존 README가 있으면 중복 섹션을 합치고 정보가 더 정확한 쪽을 남긴다.
- 확인 근거가 없는 오래된 내용은 삭제하지 말고 "확인 필요"로 표시한다.
- 문서의 제목, 명령, 경로 표기가 실제 파일과 맞는지 확인한다.
결과 보고
- 생성 또는 수정한 README 경로
- 확인한 실행/테스트 명령
- TODO 또는 확인 필요로 남긴 항목
- 덮어쓰지 않고 보존한 기존 주요 내용

실행 결과 검증

루트 README.md가 존재하는가
프로젝트 목적, 빠른 시작, 주요 명령, 구조, 작업 맥락 중 프로젝트에 필요한 섹션이 포함되어 있는가
README에 적은 명령이 실제 설정 파일 또는 프로젝트 관례에서 확인된 명령인가
README에 적은 경로가 실제로 존재하는가
agent-ops 문서를 복사해 중복하지 않고 필요한 경로만 연결했는가
불확실한 내용이 단정 표현이 아니라 TODO 또는 확인 필요로 남아 있는가
검증 실패 시: README의 해당 항목만 보완하고, 근거 없는 내용을 새로 만들지 않는다.

출력 형식

## README 작성 완료

- README: README.md
- 처리 방식: <생성 | 보완 | 재작성>
- 확인한 명령:
  - <command>

## 확인 필요

- <TODO 또는 확인 필요 항목> (해당 시)

금지 사항

사용자가 명시하지 않은 상태에서 기존 README를 통째로 덮어쓰지 않는다.
확인하지 않은 설치, 실행, 테스트, 배포 명령을 사실처럼 쓰지 않는다.
README를 긴 내부 설계 문서로 만들지 않는다. 상세 규칙은 agent-ops/ 문서로 연결한다.
README에 개인 설정, 비밀값, 로컬 전용 경로를 넣지 않는다.
로드맵이나 도메인 규칙 내용을 README에 길게 복사하지 않는다.

6.7 KiB Raw Blame History