diff --git a/README.md b/README.md index 968ad5f..e9cc946 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,7 @@ agent-ops/ | `create-domain-rule` | 새 도메인 rules.md를 만들고 프로젝트 도메인 매핑에 추가 | | `update-domain-rule` | 기존 도메인 rules.md를 코드 현황에 맞게 갱신 | | `create-skill` | 새 공통 또는 프로젝트 스킬 생성 | +| `create-readme` | AI가 다음 작업에 활용할 수 있는 표준형 README 생성 | | `create-roadmap` | 한국어 기반 Goal/Phase/Milestone 로드맵 생성 | | `update-roadmap` | 기존 로드맵 상태, Milestone, Phase, 한국어 문서 형식 갱신 | | `analyze-roadmap-position` | "지금 작업이 뭐지?" 같은 질문에 활성 Milestone과 코드 상태를 함께 분석 | diff --git a/agent-ops/.version b/agent-ops/.version index 0bfff3d..5166d13 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.25 +1.1.26 diff --git a/agent-ops/GUIDE.md b/agent-ops/GUIDE.md index e3a3d67..0db5e36 100644 --- a/agent-ops/GUIDE.md +++ b/agent-ops/GUIDE.md @@ -61,11 +61,10 @@ agent-ops/ │ ├── commit-push/SKILL.md # 커밋 & 푸시 │ ├── create-domain-rule/SKILL.md # 도메인 규칙 생성 │ ├── create-skill/SKILL.md # 스킬 생성 + │ ├── create-readme/SKILL.md # README 생성 │ ├── create-roadmap/SKILL.md # Goal/Phase/Milestone 로드맵 생성 │ ├── update-roadmap/SKILL.md # 로드맵 상태/마일스톤 갱신 │ ├── analyze-roadmap-position/SKILL.md # 현재 작업 지점/남은 작업 분석 - │ ├── create-readme/SKILL.md # README 생성 - │ ├── update-readme/SKILL.md # README 정리/갱신 │ └── update-domain-rule/SKILL.md # 도메인 규칙 수정 └── project/ # 프로젝트 스킬 (수정 가능) └── /SKILL.md diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index 9d34371..24cfdb7 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -12,6 +12,7 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- README 생성 - 로드맵/마일스톤 생성·갱신 - 현재 작업 지점/남은 작업 분석 - git commit / push diff --git a/agent-ops/skills/common/create-readme/SKILL.md b/agent-ops/skills/common/create-readme/SKILL.md new file mode 100644 index 0000000..fe9875f --- /dev/null +++ b/agent-ops/skills/common/create-readme/SKILL.md @@ -0,0 +1,153 @@ +--- +name: create-readme +version: 1.0.0 +description: 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는 프로젝트 특성에 맞게 필요한 섹션만 사용하되, 기본 순서는 아래를 따른다. + +```markdown +# + +<프로젝트 목적 1~3문장> + +## 현재 상태 + +<개발 단계, 사용 가능 범위, 중요한 제약> + +## 빠른 시작 + +<설치, 실행, 테스트의 최소 명령> + +## 주요 명령 + +| 목적 | 명령 | 비고 | +|------|------|------| + +## 구조 + +| 경로 | 역할 | +|------|------| + +## 작업 맥락 + + + +## 개발 흐름 + +<브랜치, 테스트, 검증, 리뷰 또는 배포 흐름> + +## 환경 변수 + +| 이름 | 설명 | 필수 | +|------|------|------| + +## 참고 문서 + +- <관련 문서 경로> +``` + +## 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`로 가볍게 확인 + +## 실행 절차 + +1. **기존 README 처리 결정** + - `README.md`가 없으면 새로 생성한다. + - `README.md`가 있고 사용자가 덮어쓰기를 명시하지 않았으면 기존 내용을 보존하고, 필요한 섹션만 보완한다. + - 기존 README의 제품 설명, 설치/실행 명령, 경고, 라이선스, 배포 정보를 삭제하지 않는다. + +2. **프로젝트 근거 수집** + - metadata 파일에서 프로젝트 이름, 설명, scripts, dependencies, runtime을 확인한다. + - Makefile, compose 파일, CI 설정, 테스트 설정에서 실행 명령과 검증 명령을 확인한다. + - 소스 구조는 전체 정독하지 않고 README 작성에 필요한 상위 경로와 대표 진입점만 확인한다. + - 명령을 추론해야 하면 "추정"으로 쓰지 말고 TODO로 남긴다. + +3. **README 초안 작성** + - 표준 구성 순서를 기준으로 프로젝트에 맞는 섹션을 선택한다. + - 빠른 시작에는 최소 실행 경로를 짧게 쓴다. + - 주요 명령 표에는 실제로 확인한 명령만 넣는다. + - 구조 표에는 AI가 작업 범위를 잡는 데 도움이 되는 경로만 넣는다. + - 작업 맥락에는 agent-ops 문서, 로드맵, 도메인 규칙, 중요한 작업 경계를 연결한다. + +4. **기존 내용 병합** + - 기존 README가 있으면 중복 섹션을 합치고 정보가 더 정확한 쪽을 남긴다. + - 확인 근거가 없는 오래된 내용은 삭제하지 말고 "확인 필요"로 표시한다. + - 문서의 제목, 명령, 경로 표기가 실제 파일과 맞는지 확인한다. + +5. **결과 보고** + - 생성 또는 수정한 README 경로 + - 확인한 실행/테스트 명령 + - TODO 또는 확인 필요로 남긴 항목 + - 덮어쓰지 않고 보존한 기존 주요 내용 + +## 실행 결과 검증 + +- [ ] 루트 `README.md`가 존재하는가 +- [ ] 프로젝트 목적, 빠른 시작, 주요 명령, 구조, 작업 맥락 중 프로젝트에 필요한 섹션이 포함되어 있는가 +- [ ] README에 적은 명령이 실제 설정 파일 또는 프로젝트 관례에서 확인된 명령인가 +- [ ] README에 적은 경로가 실제로 존재하는가 +- [ ] agent-ops 문서를 복사해 중복하지 않고 필요한 경로만 연결했는가 +- [ ] 불확실한 내용이 단정 표현이 아니라 TODO 또는 확인 필요로 남아 있는가 +- 검증 실패 시: README의 해당 항목만 보완하고, 근거 없는 내용을 새로 만들지 않는다. + +## 출력 형식 + +```markdown +## README 작성 완료 + +- README: README.md +- 처리 방식: <생성 | 보완 | 재작성> +- 확인한 명령: + - + +## 확인 필요 + +- (해당 시) +``` + +## 금지 사항 + +- 사용자가 명시하지 않은 상태에서 기존 README를 통째로 덮어쓰지 않는다. +- 확인하지 않은 설치, 실행, 테스트, 배포 명령을 사실처럼 쓰지 않는다. +- README를 긴 내부 설계 문서로 만들지 않는다. 상세 규칙은 `agent-ops/` 문서로 연결한다. +- README에 개인 설정, 비밀값, 로컬 전용 경로를 넣지 않는다. +- 로드맵이나 도메인 규칙 내용을 README에 길게 복사하지 않는다. diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index 95db012..65a14ea 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -5,6 +5,7 @@ | agent-ops 세팅해줘, scaffold 만들어줘, 초기화해줘 | `agent-ops/skills/common/init-agent-ops/SKILL.md` | | domain rule 만들어줘, rules.md 생성, 새 도메인 규칙 | `agent-ops/skills/common/create-domain-rule/SKILL.md` | | skill 만들어줘, SKILL.md 생성, 새 스킬 추가 | `agent-ops/skills/common/create-skill/SKILL.md` | +| README 작성해줘, README 만들어줘, 프로젝트 설명 문서 만들어줘 | `agent-ops/skills/common/create-readme/SKILL.md` | | 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` | | 로드맵 업데이트, roadmap 갱신, 마일스톤 갱신, phase 변경, 현재 마일스톤 변경, 로드맵 한국어 전환, 로드맵 번역 | `agent-ops/skills/common/update-roadmap/SKILL.md` | | 지금 작업이 뭐지?, 현재 작업 분석, 어디까지 했지?, 남은 작업 뭐야 | `agent-ops/skills/common/analyze-roadmap-position/SKILL.md` |