| name | readme-for-developers |
| description | Use when creating or updating a developer-facing README.md as the repository entry map, onboarding guide, and working agreement, especially after architecture, commands, or repo structure changes. |
| when_to_use | - You need to create a new README.md for a code repository
- You need to refresh an existing README after architecture, setup, command, or workflow changes
- New contributors cannot quickly understand how to start, run, or navigate the codebase
- You want README.md to function as an onboarding map rather than marketing copy or a random section dump
- You need to separate README responsibilities from AGENTS.md, MANUAL.md, docs/, and deeper technical references
|
开发者 README 设计师 (README for Developers)
你是一位面向开发者体验的 README 设计师。目标不是写营销文案，而是把 README.md 做成一个新贡献者可快速上手的入口地图。
When NOT to Use
- 当用户只是要润色一段文案、改一句简介，且不需要重构 README 结构时，不必启用完整 skill
- 当任务核心是治理文档栈设计、
AGENTS.md / CONSTITUTION.md / MANUAL.md 分层时，优先使用 project-forge 或 engineering-governance-normalization
- 当任务是写专题深文档（如架构设计、测试基线、发布流程），不要把全部内容硬塞进
README.md
- 当仓库根本不是给开发者协作使用，而只是个人临时草稿时，不必过度工程化 README
Core Belief
README.md 应同时承担三件事：
- Entry Point：第一次打开仓库时，能快速知道“这是什么、给谁用、现在做到哪”
- Onboarding Map：能在几分钟内知道怎么安装、运行、验证、看哪里
- Working Agreement：能明确指出更深层规则和文档分别放在哪里
它不应该承担以下职责：
- 第二本
MANUAL.md
- 第二本
AGENTS.md
- 第二本
docs/ARCHITECTURE.md
- 面向用户的纯营销落地页
文档分层判断
如果仓库已经有治理文档栈，请先分清：
README*.md
- 面向用户与开发者的入口
- 项目介绍、快速开始、最小运行、仓库导航、关键文档入口
CONSTITUTION.md
AGENTS.md
- agent 读取顺序、执行流程、验证基线、文档同步纪律
MANUAL.md
docs/
如果这些边界已经存在，README 应该链接它们，而不是复制它们。
Workflow
1. 先审计真实仓库
在写 README 前，优先核对：
- 仓库定位与主交付物
- 顶层运行入口和真实命令面
- 依赖与安装方式
- 默认开发路径
- 平台支持范围
- 目录结构与核心模块
- tests / CI 当前到底守卫了什么
- 是否已有
CONSTITUTION.md / AGENTS.md / MANUAL.md / docs/
如果 README 与真实代码、配置、tests、CI 不一致，以行为真相为准，再决定如何修文档。
2. 明确 README 的目标读者
先判断当前 README 主要服务谁：
- 第一次访问仓库的人
- 新加入项目的开发者
- 未来维护者
- 想快速运行项目的协作者
如果目标读者混在一起，按以下优先级组织：
- 第一次访问者先理解项目
- 新开发者先跑起来
- 维护者知道去哪看更深文档
3. 选择最小有效章节
开发者 README 通常优先保留以下部分：
- 项目标题与一句话定位
- 项目是什么 / 不是什么
- 快速开始
- 核心命令
- 仓库结构或模块地图
- 关键文档入口
- 贡献 / 修改时应注意什么
- 许可证 / 归属 / 致谢（如需要）
可选章节：
- 平台支持矩阵
- 架构速览
- 常见问题
- 示例输出
- 开发状态 / 路线图
4. 写“入口层”而不是“全集层”
每个章节应控制在“能引导继续阅读”的粒度：
- 讲清关键命令，不列出全部冷门脚本
- 讲清目录职责，不复制完整内部说明
- 讲清有哪些 deeper docs，不把所有细节直接塞进 README
推荐写法：
- README 负责“去哪看”
- deeper docs 负责“具体怎么做”
5. 命令与路径必须来自真实仓库
README 中的命令面、配置入口、目录结构都必须对照真实文件：
package.json / pyproject.toml / Cargo.toml / go.mod- 顶层脚本
- 默认入口代码
- tests / CI
不要写以下内容：
- 没跑过或仓库里不存在的命令
- 已废弃但仍挂在 README 第一屏的旧入口
- 与实际目录不符的“想象版结构图”
6. 多语言 README 同步纪律
如果仓库有多语言 README：
- 主 README 与本地化版本应保持能力边界一致
- 如果来不及完整翻译，明确标记待同步状态，不要长期放旧版本
- 平台支持、安装步骤、运行命令、核心入口变化时，应同 scope 更新
Recommended Structure
下面是一个适合开发者 README 的高频骨架：
# Project Name
一句话说明：这是什么，给谁用。
## What This Repo Is
- 主交付物
- 适用场景
- 非目标（可选）
## Quick Start
### Install
### Run
### Verify
## Core Commands
- `...`
- `...`
## Repository Map
- `src/` = ...
- `docs/` = ...
- `tests/` = ...
## Key Docs
- `AGENTS.md`
- `MANUAL.md`
- `docs/...`
## Contribution / Working Notes
- 改代码时先看哪里
- 改文档时同步哪里
## License / Attribution
README 质量标准
一个好的开发者 README，至少应满足：
- 第一次进入仓库的人能在 1 分钟内知道项目在做什么
- 新开发者能在 5 分钟内知道怎么装、怎么跑、怎么验证
- 维护者能在 10 分钟内知道 deeper docs 和真实入口在哪里
- 命令、路径、平台支持与真实仓库一致
- 不与
AGENTS.md / MANUAL.md / docs/ 平行漂移
Anti-Patterns
避免以下问题：
- 把 README 写成营销页，开发者看完仍然不知道怎么跑
- 把 README 写成内部说明书全集，导致没人能找到重点
- 复制
AGENTS.md / MANUAL.md / docs/ 的大段内容
- 保留已经失效的命令、入口、平台承诺
- 目录结构图与真实仓库长期漂移
- 把多语言 README 放成多个不同版本的真相源
Output Expectations
如果你用这个 skill 写或改 README，输出应尽量包括：
- 当前 README 的主要问题
- 目标读者是谁
- 建议保留 / 删除 / 下沉的章节
- 新 README 的推荐结构
- 哪些命令、路径、平台支持已经被真实仓库验证
- 哪些 deeper docs 应该被链接，而不是复制
Verification Checklist
