diff --git a/AGENTS.md b/AGENTS.md index 9317ef5..1fc160a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,24 +2,60 @@ ## Documentation Style Guide -When writing or updating README.md or any documentation files, follow these rules strictly: +When writing or updating README.md or any documentation files, follow these rules strictly. +These rules apply to ALL documentation tasks: new READMEs, updates, rewrites, and doc fixes. -### Structure +### Critical Rule: Structure Over Prose -- Use structured format with tables, code blocks, and clear headings -- NOT essay-style prose -- Every section must have bilingual headers: `## 한글 제목 | English Title` -- Use Markdown tables for feature lists, tool catalogs, comparisons, and specifications -- Use numbered steps for installation/setup guides -- Include a Table of Contents if the document exceeds 200 lines +The single most important rule: **use tables and code blocks, not essays**. + +If you catch yourself writing more than 3 consecutive sentences without a table, code block, or heading, STOP and restructure. + +**BAD (essay style):** +```markdown +## Why This Exists + +Most video tools ask for settings before they ask for taste. +That sounds efficient, but it usually produces generic work. +People do not think in "pacing_profile" and "camera_language" first. +They think in references, moods, instincts, and the strange combination +of things they already love. This project exists to close that gap. +``` + +**GOOD (structured style):** +```markdown +## 소개 | Introduction + +Shorts Engine은 좋아하는 영화, 영상 스타일, 작가 취향에서 출발해 +숏폼 영상 시나리오를 자동으로 만드는 CLI 도구입니다. + +Shorts Engine is a CLI tool that starts from your personal taste +and generates short-form video scenarios automatically. +``` ### Bilingual (Korean + English) - Write every section in both Korean and English - Korean comes first, English follows immediately after -- Section headers: `## 한글 | English` +- Section headers: `## 한글 제목 | English Title` - Table content: Korean and English in the same row where practical (e.g., `설명 Description` column) - Blockquotes and important notices: Korean line, then English line +**BAD:** +```markdown +## What You Need +- n8n (`localhost:5678`) +``` + +**GOOD:** +```markdown +## 필요한 환경 | Requirements + +| 구성요소 Component | 설명 Description | +|------------------|-----------------| +| **n8n** | 워크플로우 엔진 (`localhost:5678`) | +``` + ### Real Examples Required - Every feature or tool MUST include a concrete usage example @@ -28,6 +64,56 @@ When writing or updating README.md or any documentation files, follow these rule - Use realistic Korean data, not placeholder text - Examples should demonstrate end-to-end workflow, not just API signatures +**BAD (no example):** +```markdown +### kcsc_search_codes +코드명 기준으로 빠르게 검색합니다. +``` + +**GOOD (with example):** +```markdown +### 예시 1: 콘크리트 관련 기준 찾기 | Example 1: Find Concrete Standards + +**AI에게 이렇게 말하세요 | Say this:** +\``` +콘크리트 관련 KCS 기준을 찾아줘 +\``` + +**AI가 호출하는 도구 | Tool called:** +\```python +kcsc_search_codes(keyword="콘크리트", code_type="KCS") +\``` + +**결과 예시 | Example result:** +\```json +[ + {"code": "114010", "codeName": "콘크리트 공사 일반"} +] +\``` +``` + +### Section Headers + +- NEVER use rhetorical questions as headers +- NEVER use emoji in headers +- ALWAYS use bilingual format + +**BAD:** +```markdown +## 왜 이 저장소가 필요한가 +## ⚡ 30초 요약 +## 🔒 왜 로컬 MCP가 중요한가 +## 🧰 지금 바로 되는 것 +``` + +**GOOD:** +```markdown +## 소개 | Introduction +## 주요 기능 | Key Features +## 빠른 시작 가이드 | Quick Start Guide +## 실전 사용 예시 | Real-World Usage Examples +``` + ### Tone and Format - Direct and concise -- lead with what something does, not why it exists @@ -37,31 +123,53 @@ When writing or updating README.md or any documentation files, follow these rule - Use **bold** for emphasis sparingly - Use tables instead of bullet lists when comparing 3+ items +**BAD (philosophical closing):** +```markdown +도구는 완성되는 것이 아니라 성숙해집니다. +기술은 결국 인간의 사유 반경을 넓혀야 합니다. +``` + +**GOOD (factual closing):** +```markdown +## 만든 사람 | Author + +**22B Labs** (sinmb79) + +문의사항이나 기여는 [Issues](https://github.com/sinmb79/repo/issues)를 이용해 주세요. +``` + ### Required Sections for README.md +Every README.md must include these sections in this order: + 1. Project title + one-line description (Korean + English) -2. Badges (License, Python version, framework) +2. Badges (License, Python/Node version, framework) 3. Introduction (2-3 sentences max, Korean + English) -4. Who Is This For (table format) +4. Who Is This For (table format with target users) 5. Key Features (tables with tool/feature descriptions) 6. Quick Start Guide (numbered steps with actual commands) -7. Real-World Usage Examples (3-5 examples with input/output) -8. Project Structure (tree diagram) +7. Real-World Usage Examples (3-5 examples with actual input/output) +8. Project Structure (tree diagram with bilingual comments) 9. FAQ or Troubleshooting (if applicable) -10. Known Limitations +10. Known Limitations (if applicable) 11. Disclaimer (if applicable) 12. License 13. Author + contact -### What NOT to Do +### What NOT to Do -- Checklist -- Do NOT write in essay or blog style -- Do NOT use rhetorical questions as section headers (e.g., "Why is this important?") -- Do NOT start with philosophy or motivation -- put that in a one-line blockquote if needed -- Do NOT list features without examples -- Do NOT use emoji as bullet points or section markers -- Do NOT write long paragraphs explaining design decisions -- use a table or one-liner instead -- Do NOT assume the reader knows MCP, HWPX, or domain-specific terms -- explain briefly on first use +Before submitting any documentation, verify NONE of these appear: + +- [ ] Essay or blog-style prose (more than 3 sentences without structure) +- [ ] Rhetorical questions as section headers ("Why is this important?") +- [ ] Philosophy or motivation paragraphs (put in a one-line blockquote if needed) +- [ ] Features listed without concrete examples +- [ ] Emoji used as bullet points or section markers +- [ ] Long paragraphs explaining design decisions (use a table or one-liner) +- [ ] Monolingual content (Korean-only or English-only sections) +- [ ] Tool/feature names without `code formatting` +- [ ] Missing "Who Is This For" section +- [ ] Missing "Real-World Usage Examples" section ## Code Style @@ -70,3 +178,17 @@ When writing or updating README.md or any documentation files, follow these rule - Prefer simple, readable solutions over clever abstractions - Write tests for new functionality - Keep commits atomic and well-described + +## Commit Message Style + +``` +docs: README를 국문/영문 병행 실전 가이드로 전면 개편 + +- 구체적인 변경 사항 1 +- 구체적인 변경 사항 2 +- 구체적인 변경 사항 3 +``` + +- Use Korean for the commit title when the change is documentation +- Use bullet points for specific changes +- Keep the title under 72 characters