docs-codebase by vasilyu1983/ai-agents-public
npx skills add https://github.com/vasilyu1983/ai-agents-public --skill docs-codebase清晰、可维护技术文档的即用模式。
现代最佳实践(2026年1月):文档即代码、所有权 + 审查节奏、文档质量保证门控(链接/样式/拼写)、AI辅助起草 + 审查、流式模式重要的 OpenAPI 3.2.0,以及面向 AI 搜索的 GEO(生成式引擎优化)。
| 文档类型 | 模板 | 使用场景 |
|---|---|---|
| 项目 README | readme-template.md | 新项目、入职 |
| 架构决策记录 | adr-template.md | 技术决策 |
| API 参考 | api-docs-template.md | REST/GraphQL API |
| 更新日志 |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 版本历史 |
| 贡献指南 | contributing-template.md | 开源、团队协作 |
assets/ 中最接近的模板开始并调整。当仓库的 docs/ 文件夹包含大量供 LLM 使用的研究笔记和由 LLM 生成的实现文档时,使用此模式。
教程、操作指南、参考、说明)对每个文件进行分类。status: draft | canonical | integrated | superseded
owner: @username
last_verified: 2026-02-24
integrates_into: docs/path/to/canonical-doc.md
delete_by: 2026-03-31
AGENTS.md、README.md,以及 docs/ 下最少的规范文档(instructions、specs、reference-data)。docs/ 中创建 .archive/ 镜像,除非保留是强制性的。User needs: [Documentation Task]
├─ Repo has a docs folder with many LLM-generated docs? → **Revamp Mode** (inventory → canonicalize → trim)
├─ New project? → **README.md**
├─ Technical decision? → **ADR**
├─ Building API? → **OpenAPI spec** + api-docs-template
├─ New version? → **CHANGELOG.md**
├─ Team collaboration? → **CONTRIBUTING.md**
├─ Documenting code? → **Docstrings** (JSDoc, Python)
└─ Building docs site? → **MkDocs** (Python) or **Docusaurus** (JS)
优先使用 AGENTS.md 作为跨工具的唯一事实来源。如果特定工具需要不同的文件名(例如:Claude Code 使用 CLAUDE.md),仅当你希望跨工具内容完全一致时,才通过符号链接保持同步。
# 如果 `CLAUDE.md` 不存在且你希望内容一致:
ln -s AGENTS.md CLAUDE.md
当文档主要由 AI 智能体(AGENTS.md、CLAUDE.md、编码助手的规范文档)消费时,过时文档成为一种独特的错误类别。
阅读过时文档的智能体会:
gpt-4o 时却写 "Claude Haiku")规则: 将文档更新视为功能 PR 的一部分,而不是后续任务。
临时调查文档(质量保证报告、研究导出、审计发现)绝不能成为永久性的错误事实来源。
每个带日期的报告文件必须包含生命周期元数据:
---
Status: pending-integration | integrated | superseded
Integrates-into: docs/product/pricing-feature-matrix.md
Owner: @username
Delete-by: 2026-03-15
---
工作流程:
Status: pending-integration 的报告Status: integrated 并附上日期Delete-by 日期后删除(git 历史记录会保留一切)与其删除审计发现,不如添加一个状态列:
| 缺口 | 状态 | 修复于 |
|---|---|---|
| 免费用户可见的图表方面 | 已修复 | PR #26 |
| 免费用户无限梦想 | 已修复 | PR #26 |
| 询问 Cosmos 无速率限制 | 待处理 | — |
这既保留了审计跟踪,又显示了当前状态。智能体可以快速扫描 待处理 的项目。
将规划文档整合到规范文档时:
git show 查看已删除文件,以恢复规划中遗漏的任何独特数据即使再彻底的整合计划也会遗漏仅存在于单一源文档中的独特数据。
integrated 并按 delete_by 删除(默认:删除,而非归档)。AGENTS.md 和用于项目导航的 README.md。docs/ 文件夹应仅为 LLM 消费暴露一个小的规范集:当前指令集、当前规格和持久性参考数据。在合并 LLM 生成的文档之前,要求:
对于外部来源的数据(竞争对手定价、API 速率限制、第三方能力):
> 截至 2026 年 2 月的价格 — 请在 [来源] 核实当前定价。
过时免责声明比潜在错误的数字更安全。智能体消费文档中的错误数字会导致错误的实现决策。
向决策日志添加条目时(例如 ### D039 — 功能名称):
# 添加前始终检查最新的条目编号
grep -o '### D[0-9]*' docs/decision-log.md | tail -1
当两个决策在未检查的情况下快速连续记录时,会发生编号冲突。
当实现状态发生变化时(例如待办事项里程碑完成),在同一交付周期内同步规范文档,以防止为人类和智能体提供过时的指导。
integrated 或 superseded)和 delete_by。一个功能在以下条件满足前,文档不算完成:
| 资源 | 用途 |
|---|---|
| references/readme-best-practices.md | README 结构、徽章 |
| references/adr-writing-guide.md | ADR 生命周期、示例 |
| references/changelog-best-practices.md | Keep a Changelog 格式 |
| references/api-documentation-standards.md | REST、GraphQL、gRPC 文档 |
| references/code-commenting-guide.md | 文档字符串、内联注释 |
| references/contributing-guide-standards.md | CONTRIBUTING.md 结构 |
| references/docs-as-code-setup.md | MkDocs、Docusaurus、CI/CD |
| references/writing-best-practices.md | 清晰沟通 |
| references/markdown-style-guide.md | Markdown 格式化 |
| references/documentation-testing.md | Vale、markdownlint、cspell |
| references/ai-documentation-tools.md | Mintlify、DocuWriter、GEO |
| references/production-gotchas-guide.md | 记录平台问题 |
| references/documentation-metrics.md | 文档质量、新鲜度、覆盖率评分 |
| references/onboarding-documentation.md | 开发者上手指南、第 1 天-第 4 周 |
| references/runbook-writing-guide.md | 操作手册、事件响应 |
| references/backlog-status-sync-pattern.md | 多文档仓库的规范待办事项状态同步工作流程 |
| 技能 | 用途 |
|---|---|
| qa-docs-coverage | 文档缺口审计 |
| dev-api-design | REST API 模式 |
| dev-git-workflow | 约定式提交 |
| docs-ai-prd | PRD 模板 |
每周安装量
87
仓库
GitHub 星标数
49
首次出现
2026年1月23日
安全审计
安装于
opencode70
gemini-cli69
cursor69
codex66
github-copilot64
claude-code58
Execution-ready patterns for clear, maintainable technical documentation.
Modern best practices (January 2026) : docs-as-code, ownership + review cadence, documentation QA gates (links/style/spelling), AI-assisted drafting + review, OpenAPI 3.2.0 where streaming schemas matter, and GEO (Generative Engine Optimization) for AI search.
| Documentation Type | Template | When to Use |
|---|---|---|
| Project README | readme-template.md | New project, onboarding |
| Architecture Decision | adr-template.md | Technical decisions |
| API Reference | api-docs-template.md | REST/GraphQL APIs |
| Changelog | changelog-template.md | Version history |
| Contributing Guide | contributing-template.md | Open source, teams |
assets/ and adapt.Use this mode when a repo's docs/ folder contains substantial research notes for LLMs and implementation docs generated by LLMs.
Tutorial, How-to, Reference, Explanation).status: draft | canonical | integrated | superseded
owner: @username
last_verified: 2026-02-24
integrates_into: docs/path/to/canonical-doc.md
delete_by: 2026-03-31
3. For each topic/feature, keep exactly one canonical spec/reference and merge all duplicates into it.
4. Keep only durable facts/decisions in canonical docs; move exploration detail to short linked evidence notes.
5. Keep a compact LLM doc library with root anchors: AGENTS.md, README.md, and minimal canonical docs under docs/ (instructions, specs, reference-data).
6. Delete integrated drafts on schedule; avoid .archive/ mirrors in docs/ unless retention is mandatory.
User needs: [Documentation Task]
├─ Repo has a docs folder with many LLM-generated docs? → **Revamp Mode** (inventory → canonicalize → trim)
├─ New project? → **README.md**
├─ Technical decision? → **ADR**
├─ Building API? → **OpenAPI spec** + api-docs-template
├─ New version? → **CHANGELOG.md**
├─ Team collaboration? → **CONTRIBUTING.md**
├─ Documenting code? → **Docstrings** (JSDoc, Python)
└─ Building docs site? → **MkDocs** (Python) or **Docusaurus** (JS)
Prefer AGENTS.md as the cross-tool source of truth. If a specific tool requires a different filename (example: Claude Code uses CLAUDE.md), keep it aligned via a symlink only when you want identical content across tools.
# If `CLAUDE.md` does not exist and you want identical content:
ln -s AGENTS.md CLAUDE.md
When documentation is consumed primarily by AI agents (AGENTS.md, CLAUDE.md, canonical docs for coding assistants), stale docs become a distinct category of bug.
An agent reading stale docs will:
gpt-4o)Rule: Treat doc updates as part of the feature PR, not as a follow-up task.
Temporary investigation docs (QA reports, research exports, audit findings) must not become permanent false sources of truth.
Every dated report file must carry lifecycle metadata:
---
Status: pending-integration | integrated | superseded
Integrates-into: docs/product/pricing-feature-matrix.md
Owner: @username
Delete-by: 2026-03-15
---
Workflow:
Status: pending-integrationStatus: integrated with dateDelete-by date (git history preserves everything)Instead of deleting audit findings, add a Status column:
| Gap | Status | Sealed In |
|---|---|---|
| Chart aspects visible to free | Sealed | PR #26 |
| Dreams unlimited for free | Sealed | PR #26 |
| Ask Cosmos no rate limit | Open | — |
This preserves the audit trail while showing current state. Agents can quickly scan for Open items.
When consolidating planning docs into canonical docs:
git show deleted files to recover any unique data missed in planningEven thorough consolidation plans miss unique data that only lived in one source doc.
integrated and remove it by delete_by (default: delete, not archive).AGENTS.md for agent behavior/instructions and README.md for project navigation.docs/ folder should expose only a small canonical set for LLM consumption: current instruction sets, current specs, and durable reference data.Before merging LLM-generated docs, require:
For externally-sourced data (competitor pricing, API rate limits, third-party capabilities):
> Prices as of Feb 2026 — verify current pricing at [source].
A staleness disclaimer is safer than a potentially wrong number. Wrong numbers in agent-consumed docs cause incorrect implementation decisions.
When adding entries to a decision log (e.g., ### D039 — Feature Name):
# Always check the latest entry number before adding
grep -o '### D[0-9]*' docs/decision-log.md | tail -1
Numbering collisions happen when two decisions are logged in rapid succession without checking.
When implementation status changes (for example backlog milestones completed), sync canonical docs in the same delivery cycle to prevent stale guidance for humans and agents.
integrated or superseded) and delete_by.A feature is not doc-complete until:
| Resource | Purpose |
|---|---|
| references/readme-best-practices.md | README structure, badges |
| references/adr-writing-guide.md | ADR lifecycle, examples |
| references/changelog-best-practices.md | Keep a Changelog format |
| references/api-documentation-standards.md | REST, GraphQL, gRPC docs |
| references/code-commenting-guide.md | Docstrings, inline comments |
| references/contributing-guide-standards.md | CONTRIBUTING.md structure |
| Category | Templates |
|---|---|
| Architecture | adr-template.md |
| API Reference | api-docs-template.md |
| Project Management | readme-template.md, changelog-template.md, contributing-template.md |
| Documentation Lifecycle | template-doc-sync-checklist.md |
| Docs-as-Code | docs-structure-template.md, |
| Skill | Purpose |
|---|---|
| qa-docs-coverage | Documentation gap audit |
| dev-api-design | REST API patterns |
| dev-git-workflow | Conventional Commits |
| docs-ai-prd | PRD templates |
Weekly Installs
87
Repository
GitHub Stars
49
First Seen
Jan 23, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode70
gemini-cli69
cursor69
codex66
github-copilot64
claude-code58
AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具
50,900 周安装
Reactive Resume 免费开源简历生成器 | AI辅助构建专业简历JSON
104 周安装
落地页优化专家 - AI驱动的转化率优化工具,提供可执行的文案与A/B测试方案
96 周安装
平台工程师指南:构建内部开发者平台与黄金路径模板,优化开发者体验
102 周安装
React 19、Next.js 16、Vue 3.5 前端开发专家 - 现代Web应用与组件架构模式
100 周安装
CLAUDE.md 架构师技能:为软件项目生成和优化 AI 项目指令文件,提升 Claude 代码效率
100 周安装
2025年API设计模式指南:REST、GraphQL、tRPC决策与最佳实践
99 周安装
| references/docs-as-code-setup.md | MkDocs, Docusaurus, CI/CD |
| references/writing-best-practices.md | Clear communication |
| references/markdown-style-guide.md | Markdown formatting |
| references/documentation-testing.md | Vale, markdownlint, cspell |
| references/ai-documentation-tools.md | Mintlify, DocuWriter, GEO |
| references/production-gotchas-guide.md | Documenting platform issues |
| references/documentation-metrics.md | Doc quality, freshness, coverage scoring |
| references/onboarding-documentation.md | Developer ramp-up guides, Day 1-Week 4 |
| references/runbook-writing-guide.md | Operational runbooks, incident response |
| references/backlog-status-sync-pattern.md | Canonical backlog status sync workflow for multi-doc repos |