create-readme

创建 README 和 CHANGELOG

概述

基于代码库、Git 历史记录和配置文件中的实证信息，为原始代码库生成专业的 README.md 和 CHANGELOG.md 文件，将其转变为文档完善的项目。生成的文档中的每项声明都必须能追溯到代码库中的文件、提交或配置。

适用场景

• 项目缺少 README 或 CHANGELOG 时。

• 现有文档过时、不完整或前后不一致时。

• 发布新版本前，确保变更日志是最新的。

• 重构项目，导致现有文档无法反映当前架构时。

• 引导新贡献者，而 README 无法回答“这是什么、如何运行、如何测试”等问题时。

• 用户用英语请求或提及此技能（例如：“use /create-readme”、“run create-readme”）。

• 用户用葡萄牙语请求或提及此技能（例如：“use /create-readme”、“execute create-readme”）。

不适用场景

• API 参考文档 — 改用 OpenAPI/Swagger、TypeDoc、Sphinx 或 docfx。
• 许可证文件 — 直接复制相应的许可证文本（MIT、Apache-2.0 等）。
• 代码内部文档 — 改用文档字符串、JSDoc、TSDoc 或 XML 文档注释。
• 架构图 — 使用 architecture 技能（它会转到 drawio-architecture、mermaid-architecture，并可选使用 archify），以可视化和 Markdown 形式设计系统。
• Agent 框架搭建 — 使用 create-agent-harness 来创建 CLAUDE.md/AGENTS.md 和技能脚手架。

流程

阶段 1：探索（收集证据）

开始撰写前，先分析目标代码库：

结构分析：

• 根目录树和顶层文件（ls -la、find . -maxdepth 2 -type f）
• 找出入口点（main.ts、Program.cs、__main__.py、index.js）
• 判断是单体代码库还是单包布局

技术栈检测：

• Node.js：package.json（名称、版本、脚本、依赖项、引擎）
• .NET：*.csproj、*.sln（TargetFramework、PackageReferences、SDK 版本）
• Python：pyproject.toml、setup.py、requirements.txt、Pipfile
• Java：pom.xml、build.gradle（groupId、artifactId、Java 版本）
• Go：go.mod（模块路径、Go 版本、依赖项）
• Rust：Cargo.toml（名称、edition、依赖项）
• Docker：Dockerfile、docker-compose.yml（基础镜像、公开端口、服务）
• CI/CD：.github/workflows/、.gitlab-ci.yml、Jenkinsfile、azure-pipelines.yml

历史记录分析：

• git log --oneline -n 50 — 查看近期功能和修复
• git tag --sort=-creatordate | head -10 — 查看近期发布版本
• git log --since="last tag" --oneline — 查看尚未发布的变更

现有文档：

• 当前的 README.md 和 CHANGELOG.md（如有）— 重用有效内容
• docs/ 目录 — 作为参考，但不要重复其内容
• LICENSE 文件 — 提取许可证类型

要求：输出“探索摘要”，包含：

## Discovery Summary
- **Stack**: [languages, frameworks, versions]
- **Architecture**: [monorepo/single, layers, patterns]
- **CI/CD**: [platforms, pipelines, badges available]
- **Entry points**: [main files]
- **Test command**: [how to run tests]
- **Recent releases**: [last 3 tags]
- **Unreleased changes**: [commits since last tag]
- **Gaps**: [what's missing from current docs]

等待确认后再进入阶段 2。

阶段 2：编写 README.md

严格按照以下顺序生成 README。没有证据支持的章节应跳过，不要编造内容。

2.1 标题和徽章

• 从 package.json/*.csproj/pyproject.toml 或目录名称获取项目名称
• 徽章：CI 状态（来自工作流文件）、许可证（来自 LICENSE 文件）、版本（来自包清单）、语言覆盖率（如已配置）
• 徽章格式：[![Name](url)](link)

2.2 项目描述

• 一句话摘要（说明项目的功能及目标用户）
• 详细段落（功能和战略概述）
• 证据：从代码注释、现有文档和提交消息中提取，切勿猜测

2.3 代码库结构

project-root/
├── src/              # Source code
├── tests/            # Test suite
├── docs/             # Documentation
├── .github/workflows # CI/CD pipelines
└── package.json      # Node.js manifest

• 为每个顶层目录提供一句描述
• 仅包含实际存在的目录

2.4 技术栈

层	技术	版本
语言	TypeScript	5.x
框架	Next.js	15.x
数据库	PostgreSQL	16
CI	GitHub Actions	—

• 版本应来自软件包清单，而非猜测
• 包含运行时要求（Node 版本、Python 版本、.NET 版本）

2.5 架构

• 层级和模式（Clean Architecture、DDD、MVC、微服务）
• 如果系统包含 3 个或更多交互组件，请使用 Mermaid 图
• 依据：从目录结构和依赖关系图中推导

2.6 系统流程

• 为主要用例绘制 Mermaid 时序图／流程图
• 对于简单系统，也可以使用文字分步描述
• 仅在代码无法直观体现流程时添加

2.7 快速开始

# Prerequisites
node >= 20.x

# Install
npm install

# Configure
cp .env.example .env  # then edit values

# Run
npm run dev

• 列出带具体版本号的先决条件
• 列出环境变量（仅变量名，不包含值——链接到 .env.example）
• 使用软件包清单或 Makefile 中 scripts 里的安装和运行命令

2.8 测试与覆盖率

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

• 使用软件包清单脚本或 Makefile 中的命令
• 如果已配置覆盖率阈值，请注明（.nycrc、jest.config、coverlet）
• 如果已设置覆盖率报告，请添加徽章

2.9 业务与技术视角

• 业务：战略目标、目标用户、所解决的问题
• 技术：关键设计决策、权衡、约束
• 仅在文档、注释或提交消息中有依据时添加

2.10 许可证与状态

• 从 LICENSE 文件中确认许可证类型
• 项目状态：活跃、维护中、实验性、已弃用（根据近期提交活动判断）
• 链接到完整的许可证文本

2.11 链接

• 内部引用（docs/、CHANGELOG.md、贡献指南）
• 如果存在，添加外部引用（主页、演示、API 文档）

2.12 语言路由和 docs/ 结构

创建双语文档布局：

• README.md — 英文（en-us），始终作为主要入口页。
• README.pt-br.md — README.md 的葡萄牙语（pt-br）译文。
• docs/en/ — 根据仓库证据生成的辅助英文文档。
• docs/pt/ — 相同文档的 pt-br 版本。

docs/ 规则：

• 将每份辅助文档同时放在 docs/en/ 和 docs/pt/ 中。
• 每个 README 都应在顶部链接到对应版本：在 README.md 中使用 [Português](README.pt-br.md)；在 README.pt-br.md 中使用 [English](README.md)。
• 每个 README 都应链接到 docs/en/ 或 docs/pt/，以便查阅更深入的文档。
• 不要在 docs/ 中重复 README.md 的内容。将扩展内容／辅助内容放在此处（例如 ARCHITECTURE.md、CONTRIBUTING.md、API.md、INSTALL.md）。
• 仅在仓库中有依据时才生成文档。切勿编造辅助文档。
• 两个文件夹中的文件名保持一致（例如 docs/en/CONTRIBUTING.md 和 docs/pt/CONTRIBUTING.md）。

可考虑创建的循证文档：

• ARCHITECTURE.md — 如果已识别出架构模式或图表。
• CONTRIBUTING.md — 如果存在 .github/CONTRIBUTING.md 或提交规范。
• API.md — 如果项目提供 REST／GraphQL API（如果存在 OpenAPI/Swagger，请添加链接）。
• INSTALL.md — 如果设置过程包含 README 之外的平台特定步骤。

规则：

• 在适用时重用现有内容——不要改写已有的正确内容
• 仅包含有具体依据的章节
• README.md 始终使用 en-us；README.pt-br.md 是 pt-br 译文
• 辅助文档放在 docs/en/ 和 docs/pt/ 下，且不得重复 README 内容
• 切勿硬编码机密、API 密钥或环境变量值

第 3 阶段：编写 CHANGELOG.md

遵循 Keep a Changelog 和 SemVer 标准：

3.1 结构

# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New feature X (commit abc123)

### Fixed
- Bug Y in module Z (commit def456)

## [1.2.0] - 2025-01-15

### Added
- Feature A

### Changed
- Updated dependency B to v2.0

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/releases/tag/v1.2.0

3.2 类别

• Added — 新功能
• Changed — 现有功能的变更
• Deprecated — 即将移除的功能
• Removed — 已移除的功能
• Fixed — 错误修复
• Security — 漏洞修复

3.3 来源

• 通过分析 git log --since="last tag" --oneline 填充 [Unreleased]
• 将提交前缀（feat:、fix:、breaking:）映射到变更日志类别
• 对于过去的版本，使用标签之间的 git log v1.1.0..v1.2.0 --oneline
• 如果不存在标签，则根据最近的 50 次提交创建 [Unreleased]

3.4 链接

• 将版本号链接到 GitHub 比较 URL：https://github.com/{owner}/{repo}/compare/v{prev}...v{curr}
• 将标签链接到发布页面：https://github.com/{owner}/{repo}/releases/tag/v{version}

第 4 阶段：交付与验证

4.1 分支

创建专用分支：

git checkout -b feature/{YYYYMMDD}-readme-changelog

4.2 代码检查

• 如有可用的 Markdown 检查工具，请运行（markdownlint、remark、vale）
• 检查是否存在失效的内部链接
• 验证 Mermaid 图表语法（如果包含）

4.3 提交

使用 Conventional Commits：

git commit -m "docs(readme): update README and CHANGELOG

- Add tech stack table from package.json analysis
- Add getting started section with verified commands
- Populate CHANGELOG [Unreleased] from git log since v1.2.0

Generated with [Devin](https://devin.ai)"

4.4 报告

提供变更摘要：

## Summary
- **README.md**: [created/updated] — en-us primary, added sections X, Y, Z
- **README.pt-br.md**: [created/updated] — pt-br translation
- **docs/en/** and **docs/pt/**: [created/updated] — auxiliary docs by language
- **CHANGELOG.md**: [created/updated] — added [Unreleased] with N entries
- **Evidence**: all claims traced to files/commits in Discovery Summary

不要自动创建 PR——让人工审核者决定。

常见错误

错误	影响	修正方法
编造信息	README 声称存在实际并不存在的功能	每项说明都必须有文件、提交或配置作为依据
通用模板	README 未能体现实际架构	使用 Discovery Summary 针对每个章节进行调整
忽略历史记录	变更日志与 Git 提交不符	使用标签之间的 git log 作为事实来源
硬编码密钥	README 中包含 API 密钥或密码	仅使用环境变量名称；链接到 .env.example
徽章过时	CI 徽章指向错误的工作流	验证徽章 URL 与实际工作流文件名一致
手动创建 PR	PR 未经审核便已创建	先汇总变更；由人工创建 PR
语言错误	pt-BR 项目的 README 使用英语	与现有文档的语言保持一致
	仅有一种语言	仓库未覆盖 pt-br 用户
	文档重复 README	docs/en/README.md 或 docs/pt/README.md 复制了 README

验证清单

• 生成前已提供并确认 Discovery Summary
• README 根据现有证据包含所有必需章节
• 各章节均不含编造或无法验证的信息
• 技术栈版本与软件包清单完全一致
• 已根据 scripts/Makefile 验证快速入门命令
• 不含密钥、API 密钥或环境变量值
• CHANGELOG 遵循 “Keep a Changelog” 格式，并包含全部 6 个类别
• CHANGELOG 的 [Unreleased] 章节与自上一个标签以来的 git log 一致
• 版本链接指向有效的比较或发布 URL
• Mermaid 图表（如有）语法有效
• 分支命名遵循项目约定
• 提交消息遵循 Conventional Commits
• 已将 README.md 翻译为 pt-br，并生成 README.pt-br.md
• docs/en/ 和 docs/pt/ 已创建，用于存放辅助文档
• 语言切换器链接关联 README.md 和 README.pt-br.md
• docs/ 中未重复放置 README.md 的内容

参考资料

• Keep a Changelog
• 语义化版本
• Conventional Commits
• Shields.io — 徽章生成
• makeareadme.com — README 最佳实践