README Generator

Generate comprehensive bilingual README documentation that accurately reflects your project's structure, features, and usage patterns.

When to Apply

• •User asks to generate, create, or update README documentation
• •User mentions README.md, README.zh-CN.md, or project documentation
• •Project needs documentation updates after significant changes
• •New project requiring initial documentation

Core Principles

1. •Accuracy First: Analyze actual code, not assumptions
2. •Bilingual Consistency: Keep English and Chinese versions in sync
3. •Project Context: Match existing documentation style and tone
4. •Comprehensive Coverage: Include all essential sections

Generation Workflow

Phase 1: Analysis

Before writing, gather information:

Required Reading:

• •package.json - Project metadata, scripts, dependencies
• •AGENTS.md or similar - Development guidelines
• •Existing README files - Current style and structure
• •src/ structure - Architecture and components
• •tsconfig.json, vite.config.ts - Build configuration

Optional Reading (if exists):

• •CONTRIBUTING.md - Contribution guidelines
• •CHANGELOG.md - Version history
• •LICENSE - License information
• •.github/workflows/ - CI/CD setup
• •Docker files - Deployment info

Analysis Checklist:

- [ ] Read package.json for name, description, scripts, dependencies
- [ ] Read project structure (src/, public/, scripts/)
- [ ] Read existing README if present
- [ ] Identify key features from code
- [ ] Check for internationalization (i18n/)
- [ ] Check for Docker/deployment configs
- [ ] Review build and dev scripts

Phase 2: Structure Planning

Determine which sections to include based on project type:

Always Include:

• •Project title with logo/badge (if available)
• •Description (from package.json + enhancement)
• •Features (analyze code to identify)
• •Quick Start (installation + basic usage)
• •Development (setup + common commands)

Include If Applicable:

• •Screenshots/Demo (if UI project)
• •Architecture (if complex structure)
• •API Documentation (if library/API)
• •Configuration (if configurable)
• •Docker Deployment (if Dockerfile exists)
• •Contributing Guidelines (link to CONTRIBUTING.md or inline)
• •FAQ (for common issues)
• •Roadmap (for active development)
• •Changelog (link to releases)
• •License (from package.json)
• •Acknowledgments (if using notable dependencies)

Phase 3: Content Generation

Title and Badges

# Project Name

[Badge examples - choose relevant ones:]
[![GitHub release](https://img.shields.io/github/v/release/user/repo)](https://github.com/user/repo/releases)
[![License](https://img.shields.io/github/license/user/repo)](LICENSE)
[![Node Version](https://img.shields.io/node/v/package-name)](package.json)

Description Section

• •Start with a compelling one-liner from package.json description
• •Expand with 2-3 sentences about what problem it solves
• •Highlight unique selling points
• •Keep it concise (3-5 sentences max)

Features Section

Extract features from:

• •Code structure analysis
• •Key dependencies (Vue Router → routing, Pinia → state management)
• •UI components (if web app)
• •Special functionality (virtual scrolling, i18n, etc.)

Format as bullet points with icons (optional):

## ✨ Features

- 🚀 **Modern Stack** - Vue 3 + TypeScript + Vite
- 📱 **Responsive Design** - Mobile-first UI
- 🌍 **Internationalization** - Multi-language support
- ⚡ **Performance** - Virtual scrolling for large lists

Installation Section

## 📦 Installation

### Prerequisites

- Node.js >= X.X.X
- pnpm >= X.X.X (or npm/yarn)

### Clone and Install

\`\`\`bash
git clone https://github.com/user/repo.git
cd repo
pnpm install
\`\`\`

Usage Section

Provide concrete examples:

## 🚀 Usage

### Development

\`\`\`bash
pnpm dev
\`\`\`

Open http://localhost:5173 in your browser.

### Build

\`\`\`bash
pnpm build
\`\`\`

### Preview

\`\`\`bash
pnpm preview
\`\`\`

Development Section

## 🛠️ Development

### Project Structure

\`\`\`
src/
├── api/          # API layer
├── components/   # Vue components
├── composables/  # Reusable compositions
├── store/        # Pinia stores
├── router/       # Vue Router
├── views/        # Pages
└── utils/        # Utilities
\`\`\`

### Available Scripts

| Command | Description |
|---------|-------------|
| \`pnpm dev\` | Start dev server |
| \`pnpm build\` | Production build |
| \`pnpm lint\` | Lint and fix |
| \`pnpm check\` | Type check |

### Tech Stack

- **Framework**: Vue 3 (Composition API)
- **Language**: TypeScript
- **Build Tool**: Vite
- **UI Library**: Naive UI / Element Plus / etc.
- **State Management**: Pinia
- **Routing**: Vue Router

Configuration Section (if applicable)

## ⚙️ Configuration

### Environment Variables

Create \`.env\` file:

\`\`\`env
VITE_API_BASE_URL=http://localhost:3000
VITE_APP_TITLE=My App
\`\`\`

### Available Options

| Variable | Description | Default |
|----------|-------------|---------|
| \`VITE_API_BASE_URL\` | API endpoint | - |

Docker Section (if Dockerfile exists)

## 🐳 Docker Deployment

\`\`\`bash
# Build image
docker build -t project-name .

# Run container
docker run -p 8080:80 project-name
\`\`\`

Or use Docker Compose:

\`\`\`bash
docker-compose up -d
\`\`\`

Contributing Section

## 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create your feature branch (\`git checkout -b feature/amazing-feature\`)
3. Commit your changes (\`git commit -m 'feat: add amazing feature'\`)
4. Push to the branch (\`git push origin feature/amazing-feature\`)
5. Open a Pull Request

License Section

## 📄 License

This project is licensed under the [MIT License](LICENSE).

Phase 4: Bilingual Generation

Translation Strategy

1. •Generate English version first (README.md)
2. •Translate to Chinese (README.zh-CN.md)
3. •Ensure consistency:
   • •Technical terms: Keep English or add Chinese translation in parentheses
   • •Code examples: Identical in both versions
   • •File paths: Identical in both versions
   • •Version numbers: Identical in both versions

Chinese Translation Guidelines

Technical Terms Translation:

Keep in English:

• •Package names (npm, pnpm, Vite, Vue, etc.)
• •Command names (dev, build, lint)
• •File paths and code
• •URLs and links
• •Version numbers

Example Chinese Title:

# 项目名称

> 项目简介的中文翻译

[中文] | [English](README.md)

Phase 5: File Linking

Add language switcher at the top of each README:

README.md:

[English](README.md) | [简体中文](README.zh-CN.md)

README.zh-CN.md:

[English](README.md) | [简体中文](README.zh-CN.md)

Phase 6: Validation

Before finalizing, verify:

Content Accuracy:

• • All scripts mentioned exist in package.json
• • File paths match actual structure
• • Version numbers are current
• • URLs are valid (repo, issues, homepage)
• • Dependencies mentioned are actually used

Consistency:

• • English and Chinese versions have same structure
• • Code blocks are identical in both versions
• • All links work in both versions
• • Technical accuracy is maintained in translation

Completeness:

• • No placeholder text (TODO, FIXME, etc.)
• • No broken links
• • All sections have content
• • Examples are concrete and testable

Style:

• • Matches existing project documentation style
• • Consistent formatting (headings, lists, code blocks)
• • Professional tone
• • Clear and concise language

README Templates

Minimal Template (Basic Projects)

# Project Name

[Language switcher]

## 📖 Description

[1-2 paragraphs describing the project]

## ✨ Features

- Feature 1
- Feature 2
- Feature 3

## 📦 Installation

\`\`\`bash
npm install
\`\`\`

## 🚀 Usage

\`\`\`bash
npm run dev
\`\`\`

## 📄 License

[License information]

Standard Template (Most Projects)

Use the sections outlined in Phase 3, including:

• •Title + Badges
• •Description
• •Features
• •Installation (with prerequisites)
• •Usage
• •Development
• •Contributing
• •License

Comprehensive Template (Complex Projects)

Add to standard template:

• •Screenshots/Demo
• •Architecture diagram or explanation
• •API Documentation
• •Configuration details
• •Docker deployment
• •FAQ
• •Roadmap
• •Changelog link
• •Acknowledgments

Common Patterns

Vue Project README

Key sections to emphasize:

• •Tech stack (Vue version, TypeScript, build tool)
• •Project structure (src/ organization)
• •Component architecture
• •State management approach
• •Development workflow
• •Build and deployment

Library/Package README

Key sections to emphasize:

• •Installation via package manager
• •API documentation
• •Usage examples with code
• •TypeScript types
• •Browser compatibility
• •Bundle size

Full-Stack Project README

Key sections to emphasize:

• •Architecture overview (frontend + backend)
• •Separate setup instructions
• •Environment variables
• •API endpoints
• •Database setup
• •Deployment guide

Tips for Quality README

1. •Show, Don't Tell: Use code examples instead of describing
2. •Be Specific: "npm run dev starts on port 5173" not "run dev server"
3. •Test Everything: Every command should actually work
4. •Keep It Updated: README should match current code state
5. •Use Visuals: Screenshots for UI, diagrams for architecture
6. •Link Liberally: Link to detailed docs, issues, wiki
7. •Consider Audience: Adjust detail level for target users

Anti-Patterns to Avoid

❌ Placeholder Content

## Features
TODO: Add features list

❌ Outdated Information

npm install express@3.0.0  # Project actually uses v4

❌ Vague Instructions

Install dependencies and run the app

❌ Broken Links

[Documentation](docs/guide.md)  # File doesn't exist

❌ Inconsistent Bilingual Content

# English has 10 sections
# Chinese has 6 sections

❌ Machine Translation Quality

# Use natural language, not word-by-word translation

Handling Updates

When updating existing README:

1. •Preserve Style: Match existing formatting and tone
2. •Incremental Changes: Don't rewrite unless requested
3. •Keep History: Maintain existing badges, acknowledgments
4. •Sync Languages: Update both English and Chinese
5. •Validate Links: Ensure all existing links still work

Example Workflow

User: "Generate README for this project"

Agent:
1. Read package.json → Get name, description, scripts, dependencies
2. Read src/ structure → Understand architecture
3. Check for existing README → Analyze style
4. Check for i18n/ → Project has internationalization
5. Check for Dockerfile → Project supports Docker
6. Generate comprehensive README.md (English)
7. Translate to README.zh-CN.md (Chinese)
8. Add language switcher to both
9. Validate all commands and links
10. Present both files to user

Additional Resources

For reference when generating README:

• •Badges: shields.io for status badges
• •Emojis: gitmoji for commit/section emojis
• •Markdown: GitHub Flavored Markdown
• •Examples: Search "awesome readme" on GitHub for inspiration

Summary

When generating README documentation:

1. •✅ Analyze project thoroughly before writing
2. •✅ Match content to project complexity and type
3. •✅ Generate English first, then translate to Chinese
4. •✅ Ensure bilingual consistency
5. •✅ Validate all commands, paths, and links
6. •✅ Use concrete examples, not vague descriptions
7. •✅ Keep it maintainable and up-to-date