readme-craft

README 编写

有关通用技术写作模式，请参阅 technical-writer 技能。

常见问题

• 一上来就讲安装 -> 先给出 TL;DR 和价值主张
• 描述它是什么 -> 描述它解决什么问题
• 没有示例 -> 每项功能至少提供一个示例
• 隐藏限制 -> 设置专门的限制说明章节
• 只有一种安装方式 -> 提供 3 种以上途径

黄金结构

第 1 层：主视觉区

<p align="center">
  <img src="logo.png" width="200" alt="Project Name">
</p>

<p align="center">
  <a href="..."><img src="https://img.shields.io/..." alt="CI"></a>
  <a href="..."><img src="https://img.shields.io/..." alt="Version"></a>
  <a href="..."><img src="https://img.shields.io/..." alt="License"></a>
</p>

<p align="center">
  <b>One-line description of what problem this solves</b>
</p>

```bash
curl -sSL https://example.com/install.sh | bash

Badge templates: see [references/badge-reference.md](references/badge-reference.md)

### Tier 2: TL;DR

```markdown
## TL;DR

**Problem:** [Specific pain point users face]

**Solution:** [How this tool solves it]

| Feature | Benefit |
|---------|---------|
| Feature 1 | Quantified benefit |
| Feature 2 | Quantified benefit |
| Feature 3 | Quantified benefit |

第 3 层：快速入门

## Quick Start

# 1. Install
curl -sSL https://example.com/install.sh | bash

# 2. Initialize
mytool init

# 3. Run core workflow
mytool process input.txt --output result.json

# 4. Verify
mytool status

规则： 使用 5–10 条命令展示核心工作流。

第 4 层：参考章节

• 设计理念／设计决策
• 替代方案比较
• 安装（多种方式）
• 命令参考
• 配置选项
• 架构（适用于复杂系统）

第 5 层：支持章节

• 故障排除
• 限制
• 常见问题
• 贡献指南
• 许可证

章节模板

比较表

## Why [Tool] Over Alternatives?

| Feature | [Tool] | Alternative A | Alternative B |
|---------|--------|---------------|---------------|
| Speed | 50ms | 200ms | 150ms |
| Memory | 10MB | 50MB | 30MB |
| Feature X | Yes | No | Partial |

**Choose [Tool] when:** [specific use case]
**Choose Alternative A when:** [specific use case]

安装（多种方式）

## Installation

### Quick Install (Recommended)

```bash
curl -sSL https://example.com/install.sh | bash

包管理器

# macOS
brew install mytool

# Linux
apt install mytool  # Debian/Ubuntu
dnf install mytool  # Fedora

# Windows
winget install mytool

从源码安装

git clone https://github.com/user/mytool
cd mytool
make install

### Command Reference

```markdown
## Commands

### Global Flags

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Increase output verbosity |
| `-q, --quiet` | Suppress non-error output |
| `--config PATH` | Use custom config file |

### `mytool init`

Initialize a new project.

```bash
mytool init                    # Interactive setup
mytool init --template minimal # Use template
mytool init --force            # Overwrite existing

### Troubleshooting

```markdown
## Troubleshooting

### Error: "Permission denied"

**Cause:** Installation script lacks execute permissions.

**Fix:**
```bash
chmod +x install.sh
./install.sh

错误：“Command not found”

原因： 二进制文件不在 PATH 中。

修复方法：

export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc for persistence

### Limitations

```markdown
## Limitations

**Current constraints:**

| Limitation | Workaround | Planned Fix |
|------------|------------|-------------|
| Max 10MB files | Split large files | v2.0 |
| No Windows GUI | Use WSL | Under review |
| Single-threaded | Use multiple instances | v1.5 |

**Out of scope:**
- Feature X (use [Alternative] instead)
- Feature Y (not planned)

常见问题

## FAQ

<details>
<summary><b>Q: How does this compare to [Alternative]?</b></summary>

[Tool] focuses on [specific strength], while [Alternative] excels at [different use case].

</details>

发布前检查清单

主视觉区：

• 已添加 Logo／图片
• 徽章为最新且可正常使用
• 用一句话描述所解决的问题
• 快速安装命令清晰可见

内容：

• 首屏内包含 TL;DR
• 每项功能都有示例
• 代码块可直接复制粘贴运行
• 文档说明了 3 种以上安装方式

可信度：

• 与替代方案进行了比较（客观诚实）
• 已说明限制
• 故障排除部分列出了最常见的 5 个错误
• 已验证所有链接

反面模式

不要这样做	应当这样做
从安装说明开始	从价值主张开始
“这是一个……工具”	“这个工具解决……”
只用截图演示	提供可执行代码块
只提出主张，不给示例	每项功能都提供示例
隐藏限制	设置专门的章节说明限制

参考示例

参考以下项目，学习优秀的 README 编写模式：

• ripgrep - 基准测试数据、对比矩阵
• bat - 功能亮点、可视化演示
• starship - 配置预设、安装矩阵
• jq - 渐进式教程、手册链接