Update documentation from Claude Code

2026-07-06 11:32:35 +08:00
parent fae7fda88c
commit 53d6430ea0
22 changed files with 345 additions and 423 deletions
@@ -30,3 +30,9 @@ business/

 - [`../docs/02-requirements.md`](../docs/02-requirements.md)
 - [`../docs/06-tasks.md`](../docs/06-tasks.md)
+
+跨目录的单一事实来源约定：
+
+- AI 友好度评分维度：唯一权威在 [`../docs/04-architecture.md`](../docs/04-architecture.md)，本目录文档只引用。
+- 任务清单：唯一权威在 [`../docs/06-tasks.md`](../docs/06-tasks.md)，本目录文档不维护任务状态。
+- 站点语言决策（第一版英文单语言）：依据在 [`content-strategy.md`](content-strategy.md)，需求口径在 [`../docs/02-requirements.md`](../docs/02-requirements.md)。
@@ -15,6 +15,8 @@ Skelet 的目标是帮助用户快速回答一个具体问题：我的项目应

 第一版先做内容目录和评测闭环：按场景分类，按语言、框架、数据库和 AI 友好度筛选，提供骨架详情、适用/不适用场景、推荐理由和评分。

+第一版为**英文单语言站点**，主攻"AI Coding 友好度"这一尚无成型竞争者的差异化角度，避开 "saas boilerplate" 等已被高权重老站垄断的头部词（详见 `content-strategy.md`）。
+
 ## 二、问题与机会

 ### 2.1 用户痛点
@@ -68,16 +70,7 @@ Skelet 提供一个结构化的骨架项目数据库和评测体系。

 ### 5.2 AI 友好度评分

-评分维度：
-
-| 维度 | 说明 |
-| --- | --- |
-| 目录结构 | 是否清晰、模块边界是否明确 |
-| 文档完整度 | 是否有运行、部署、测试和架构说明 |
-| 测试可用性 | 是否有可运行测试和基础 CI |
-| 示例模块 | 是否有完整 demo feature 供 AI 模仿 |
-| 依赖克制度 | 是否依赖过重、配置是否复杂 |
-| 增量开发难度 | 是否容易让 AI 在既有模式中添加功能 |
+评分维度的**唯一权威定义**在 [`../docs/04-architecture.md`](../docs/04-architecture.md)：6 个 0-5 分项（目录结构、文档完整度、测试可用性、示例模块、依赖克制度、增量开发难度），总分由分项计算、不单独录入。本文不另行维护维度清单，避免漂移。

 ## 六、技术方案

@@ -113,7 +106,7 @@ SQLite 作为第一版上线数据库的前提：以公开读为主，后台少
 - 上手体验和避坑指南。
 - 项目维护状态观察。

-可轻量加入：Newsletter 订阅、项目提交入口、简单赞助说明页。
+可轻量加入：外部托管的 Newsletter 订阅链接（如 Buttondown，纯外链、不自建后端）、项目提交入口、简单赞助说明页。

 ### 7.2 阶段二：轻量变现

@@ -160,15 +153,19 @@ SQLite 作为第一版上线数据库的前提：以公开读为主，后台少

 Newsletter 不做泛资讯，只围绕：新发现的骨架、值得关注的模板、AI 友好度评测、项目启动建议。

-## 九、里程碑
+## 九、里程碑与验证闸门

-| 阶段 | 目标 | 交付物 |
-| --- | --- | --- |
-| M1 | MVP 可运行 | 首页、分类页、项目详情、后台录入、基础 SEO |
-| M2 | 内容初始库 | 至少 8 个场景、50 个骨架项目、10 篇评测/对比文章 |
-| M3 | SEO 验证 | 有稳定自然搜索访问和 Newsletter 订阅入口 |
-| M4 | 轻量变现 | Affiliate 和 Sponsored 规则上线 |
-| M5 | 付费产品验证 | 付费数据库、自有模板或顾问服务获得首批付费用户 |
+每个里程碑必须带**验证闸门**：闸门不通过就不追加投入，先调整方向。这是独立开发者最重要的止损纪律——最大的风险不是做得慢，而是在需求验证前投入几百小时内容劳动。
+
+| 阶段 | 目标 | 交付物 | 验证闸门 |
+| --- | --- | --- | --- |
+| M1 | MVP 可运行 | 首页、分类页、项目详情、后台录入、基础 SEO、访问统计（T-305） | 标准验证通过；核心页面可被搜索引擎索引 |
+| M2 | 内容初始库 | **2 个场景**（SaaS、内容站/CMS）× 10 个骨架项目 + 6 篇评测/对比文章 | 全部详情页评分和适合/不适合字段完整；每篇文章有明确结论 |
+| M3 | SEO 验证 | Search Console 接入、外部托管 Newsletter 订阅链接 | 上线 8 周自然搜索展示量出现持续增长趋势；**止损线：12 周自然点击仍接近 0 时，先复盘关键词方向和内容角度，不扩场景、不加内容量** |
+| M4 | 轻量变现 | Affiliate 和 Sponsored 规则上线 | 外链点击有稳定基数（依赖 T-305 数据）；至少 1 个 Affiliate 渠道产生真实点击转化 |
+| M5 | 付费产品验证 | 付费数据库、自有模板或顾问服务其一 | 获得首批 ≥3 个付费用户；价格假设经真实报价验证后才扩产品线 |
+
+**内容投入封顶原则**：在 M3 闸门通过前，内容库投入封顶在 20 个项目 + 12 篇文章以内。每个项目按收录流程认真做需要 2-4 小时，50 个项目就是 100-200 小时——这笔投入必须发生在需求验证之后，而不是之前。

 ## 十、成本结构

@@ -218,7 +215,8 @@ Newsletter 不做泛资讯，只围绕：新发现的骨架、值得关注的模
 | 商业化伤害信任 | 赞助项目影响排序 | Sponsored 明确标识，编辑推荐独立排序 |
 | 技术复杂度膨胀 | 过早做会员、支付、复杂搜索 | 第一版只做内容闭环，V2/V3 再扩展 |
 | SQLite 写入瓶颈 | 出现 database is locked | 限制第一版写入，达到触发条件后迁移 PostgreSQL |
-| SEO 起量慢 | 内容早期没有流量 | 先做高意图长尾关键词和对比内容 |
+| SEO 起量慢 | 内容早期没有流量 | 先做高意图长尾关键词和对比内容；按 M3 止损线及时复盘方向 |
+| 用户直接问 AI 选型 | 目标用户习惯直接问 Claude / ChatGPT / Cursor，不逛目录站 | 提供 LLM 训练数据里没有的东西：维护状态时效性、统一评分、不适合场景的负面信息；通过 llms.txt / 结构化数据 / JSON 导出让 AI 引用 Skelet 作为数据源（见 `competitor-analysis.md`） |

 ## 十三、第一版执行重点

@@ -8,12 +8,13 @@

 Skelet 的竞品分为几类：

-1. GitHub Topics / Search。
-2. Awesome Lists。
-3. 开源替代产品目录。
-4. 付费模板市场。
-5. 官方框架 starter。
-6. 技术博客和排行榜文章。
+1. 直接问 AI（Claude / ChatGPT / Cursor 等）——最大的隐性竞品。
+2. GitHub Topics / Search。
+3. Awesome Lists。
+4. 开源替代产品目录。
+5. 付费模板市场。
+6. 官方框架 starter。
+7. 技术博客和排行榜文章。

 Skelet 不需要在第一版取代它们，而是要做一个更适合“AI coding 项目启动选型”的中间层。

@@ -21,6 +22,7 @@ Skelet 不需要在第一版取代它们，而是要做一个更适合“AI codi

 | 类型 | 优势 | 缺点 | Skelet 机会 |
 | --- | --- | --- | --- |
+| 直接问 AI | 即问即答、结合用户自己的上下文、零切换成本 | 训练数据滞后、不知道当前维护状态、评分口径不一致、给不出可信对比来源 | 提供时效性数据和统一评测，成为 AI 引用的数据源。 |
 | GitHub Topics | 数据最全、更新快、有 stars/forks/signals | 噪声高、缺少场景判断、缺少评测 | 做筛选、归类、评测和结论。 |
 | Awesome Lists | 人工整理、覆盖细分领域 | 更新不稳定、缺少评分、链接堆砌 | 做结构化字段和维护状态追踪。 |
 | OpenAlternative / AlternativeTo | 适合找开源替代产品和行业软件 | 更多是产品目录，不是项目骨架目录 | 从成熟产品反推行业骨架需求。 |
@@ -31,6 +33,23 @@ Skelet 不需要在第一版取代它们，而是要做一个更适合“AI codi

 ## 三、直接参考对象

+### 3.0 直接问 AI（最大的隐性竞品）
+
+定位：目标用户（AI coding 使用者）现在选骨架的第一反应往往不是逛目录站，而是直接问 Claude / ChatGPT / Cursor。任何目录站的分析如果不回答"用户为什么不直接问 AI"，都是不完整的。
+
+AI 回答的真实短板（Skelet 的生存空间）：
+
+- **时效性**：训练数据滞后数月到一年以上，不知道项目当前的维护状态、最近是否 archived、依赖是否过期。
+- **一致性**：每次回答的评分口径和推荐理由都不一样，无法横向对比。
+- **负面信息缺失**："这个骨架不适合什么场景"这类负面评测在训练数据里几乎不存在。
+- **可信来源**：AI 给不出可核查的结构化对比出处。
+
+防守 + 借力策略（这既是威胁也是获客路径）：
+
+- 持续维护"维护状态 + 统一评分 + 不适合场景"这三类 AI 给不了的数据。
+- 提供 `llms.txt` 和项目数据 JSON 导出，让 AI 工具在回答选型问题时**引用 Skelet 作为数据源**——对这个站的目标用户来说，"被 AI 引用"可能是比传统 SEO 更高效的获客渠道（已列入 `../docs/06-tasks.md` Backlog）。
+- 长期可评估 MCP server 形态，让 agent 直接查询骨架数据库。
+
 ### 3.1 GitHub Topics

 定位：最大开源项目入口。
@@ -113,18 +132,18 @@ Skelet 的核心差异：

 ## 五、第一版竞争策略

-不要一开始做大而全目录。第一版只打穿 4 个高需求场景：
+不要一开始做大而全目录。**首批只打穿 2 个场景**：

-1. SaaS。
-2. 管理后台。
-3. API 服务。
-4. 内容站 / CMS。
+1. SaaS（需求量最大、变现路径最清晰）。
+2. 内容站 / CMS（作者正在用 Wagtail 建站，有一手评测经验）。
+
+管理后台和 API 服务作为第二批，在 M3（SEO 验证）闸门通过后再扩展（见 `business-plan-v1.md` 里程碑）。

 每个场景做到：

- 8-15 个高质量候选。
- 统一评分。
- 有推荐结论。
+- 约 10 个高质量候选。
+- 按 `../docs/04-architecture.md` 的统一评分维度打分。
+- 有推荐结论和不适合场景。
 - 有一篇场景推荐文章。
 - 有一篇对比文章。

@@ -132,6 +151,7 @@ Skelet 的核心差异：

 | 风险 | 说明 | 防守方式 |
 | --- | --- | --- |
+| 用户直接问 AI | AI 即问即答，用户不来目录站 | 维护 AI 给不了的时效性数据、统一评分和负面评测；用 llms.txt / JSON 导出让 AI 引用 Skelet（见 3.0）。 |
 | GitHub 数据太全 | 用户可能直接去 GitHub 搜 | Skelet 提供场景判断和 AI 友好度评分。 |
 | Awesome list 更轻 | 用户可能只需要链接 | Skelet 提供详情、对比和维护状态。 |
 | 模板市场转化强 | 付费模板有 demo 和营销 | Skelet 先建立信任，后续卖整理后的 AI 友好模板。 |
@@ -53,22 +53,29 @@ Skelet 的内容不是泛技术资讯，而是围绕一个问题展开：开发

 ## 四、关键词策略

-### 4.1 高意图关键词
+### 4.0 语言与主攻角度决策
+
+- **第一版为英文单语言站点**：英文市场变现空间更大（Affiliate、付费数据库、模板销售都以英文生态为主），且"AI Coding 友好度"角度在英文市场尚无成型竞争者。
+- **不以头部词为主攻目标**："saas boilerplate"、"django boilerplate" 这类词被 DR 80+ 的老站和模板厂商 landing 页垄断，新域名 12 个月内基本进不了首页。它们只作为长尾组合的词根使用。
+- **主攻角度：AI coding 视角的选型词**。这是本站唯一真正差异化的关键词资产，竞争小、意图高、且和产品定位完全一致。
+- 中文长尾词（4.2）保留作为后续扩展参考；MVP 明确不做中文站（与 `../docs/02-requirements.md` 口径一致）。
+
+### 4.1 主攻关键词（AI coding 角度 + 长尾组合）

 ```text
-saas boilerplate
-saas starter
-django boilerplate
-fastapi template
-nextjs saas boilerplate
-admin dashboard starter
-open source ecommerce starter
-ai app starter
-rag starter template
-wagtail starter
+ai friendly boilerplate
+best starter template for ai coding
+claude code friendly django starter
+cursor friendly nextjs boilerplate
+boilerplate for ai agents to extend
+llm friendly project structure
+saas boilerplate for solo developers（长尾组合示例）
+django starter with good docs and tests（长尾组合示例）
 ```

-### 4.2 中文长尾关键词
+头部词根（仅用于组合，不单独主攻）：saas boilerplate、saas starter、django boilerplate、fastapi template、nextjs saas boilerplate、admin dashboard starter、wagtail starter、rag starter template。
+
+### 4.2 中文长尾关键词（后续扩展参考，MVP 不做）

 ```text
 适合 AI Coding 的项目骨架
@@ -116,15 +123,17 @@ AI Coding 友好度评分

 ## 六、发布节奏

-MVP 阶段建议节奏：
+按单人投入校准的节奏（每个项目认真评测需要 2-4 小时，节奏定高了只会导致质量下降或弃更）：

 | 周期 | 内容 |
 | --- | --- |
-| 每周 | 新增 3-5 个骨架项目详情页。 |
-| 每周 | 发布 1 篇评测或对比文章。 |
-| 每月 | 完成 1 个场景专题页。 |
+| 每周 | 新增 2-3 个骨架项目详情页。 |
+| 每两周 | 发布 1 篇评测或对比文章。 |
+| 每月 | 复盘 Search Console 数据，校准关键词方向。 |
 | 每季度 | 更新高流量文章和核心榜单。 |

+**投入封顶**：M3（SEO 验证）闸门通过前，内容库封顶 20 个项目 + 12 篇文章（见 `business-plan-v1.md` 里程碑）。先验证需求，再扩内容。
+
 ## 七、质量标准

 每篇内容必须满足：
@@ -149,20 +158,25 @@ MVP 阶段建议节奏：

 ## 九、第一批内容建议

-优先做 12 篇内容：
+共 12 篇（英文撰写，下列为中文题意）。前 6 篇围绕首批 2 个场景（SaaS、内容站/CMS）优先完成，对应 M2 交付物；后 6 篇在 M3 验证期间视数据补充：
+
+优先 6 篇：

 1. 适合 AI Coding 的开源 SaaS 骨架推荐。
-2. Python Web 项目骨架怎么选。
-3. Django 项目从 Cookiecutter Django 开始是否合适。
-4. FastAPI 全栈模板适合什么项目。
-5. Wagtail 做内容目录站的优缺点。
-6. Next.js SaaS Boilerplate 对比。
-7. 管理后台项目应该选什么骨架。
-8. API 服务骨架选择指南。
-9. 内容网站骨架选择指南。
-10. 2 核 2G VPS 部署 Python Web 项目策略。
-11. AI Coding 友好度评分标准说明。
-12. 为什么大而全模板不一定适合 MVP。
+2. AI Coding 友好度评分标准说明（本站方法论的锚点内容）。
+3. 内容网站骨架选择指南。
+4. Wagtail 做内容目录站的优缺点。
+5. Next.js SaaS Boilerplate 对比。
+6. 为什么大而全模板不一定适合 MVP。
+
+第二批 6 篇：
+
+7. Python Web 项目骨架怎么选。
+8. Django 项目从 Cookiecutter Django 开始是否合适。
+9. FastAPI 全栈模板适合什么项目。
+10. 管理后台项目应该选什么骨架（场景扩展后）。
+11. API 服务骨架选择指南（场景扩展后）。
+12. 2 核 2G VPS 部署 Python Web 项目策略。

 ## 十、指标

@@ -90,7 +90,7 @@
 - 项目启动组合建议。
 - 导出对比表。

-价格假设：
+价格假设（**未经验证**，进入 M5 前必须用真实报价或预售验证，不作为收入预测依据）：

 | 版本 | 价格假设 | 内容 |
 | --- | --- | --- |
@@ -164,6 +164,6 @@ Skelet 可以出售“AI Coding 友好”的整理版模板。

 - 在数据模型中预留 `is_sponsored` 字段。
 - 内容中建立“部署建议”和“推荐组合”栏目。
- 上线 Newsletter 订阅入口。
- 先记录外部链接点击，为 Affiliate 做准备。
+- 上线**外部托管**的 Newsletter 订阅链接（如 Buttondown，纯外链、不自建后端；完整 Newsletter 功能在 V2，与 `docs/02-requirements.md` 口径一致）。
+- 接入轻量访问统计并记录外部链接点击（任务 T-305），为 Affiliate 做准备。
 - 商业规则写清楚，避免后续损害信任。
@@ -269,20 +269,21 @@ workflow automation open source

 ## 五、AI Coding 友好度评估

-每个候选项目都要按以下维度评分：
+评分维度的**唯一权威定义**在 [`../docs/04-architecture.md`](../docs/04-architecture.md)：6 个 0-5 分项，总分由分项计算、不单独录入。本文不另行维护维度清单。评审时对应的检查问题：

-| 维度 | 评分问题 |
+| 维度（定义见架构文档） | 评分问题 |
 | --- | --- |
 | 目录结构 | agent 能否快速理解入口、模块和边界？ |
 | 文档完整度 | 是否有清楚的启动、测试、部署说明？ |
 | 测试可用性 | 是否能用一条命令跑基础测试？ |
 | 示例模块 | 是否有一个完整功能供 agent 模仿？ |
 | 依赖克制度 | 是否需要大量外部账号或复杂服务才能运行？ |
-| 增量开发难度 | 新增功能是否有清晰落点？ |
-| 任务切片友好度 | 是否适合一轮只做一个小任务？ |
+| 增量开发难度 | 新增功能是否有清晰落点？是否适合一轮只做一个小任务？（原"任务切片友好度"已并入本维度） |

 评分不是只给总分，还要写一句评语：为什么适合 AI coding，为什么不适合。

+**时间成本提示**：每个项目按完整收录流程（clone、跑起来、评分、写适合/不适合）需要 2-4 小时。可先用 15 分钟粗筛（license、最近提交、README 质量）淘汰明显不合格者，只对通过粗筛的项目做完整评测。
+
 ## 六、收录流程

 推荐流程：
@@ -303,34 +304,34 @@ MVP 阶段可以先人工维护，不做自动抓取。

 ## 七、首批内容建议

-第一批不要追求全行业覆盖，建议先做 4 个高需求场景：
+第一批不要追求全行业覆盖。**首批只做 2 个场景**（与 `business-plan-v1.md` 里程碑 M2 和 `competitor-analysis.md` 一致）：

 1. SaaS
-2. 管理后台
-3. API 服务
-4. 内容站 / CMS
+2. 内容站 / CMS

-每个场景先收录 8-15 个项目，保证详情页质量，而不是快速堆数量。
+每个场景收录约 10 个项目，保证详情页质量，而不是快速堆数量。管理后台和 API 服务在 M3（SEO 验证）闸门通过后作为第二批扩展。

-第一批建议技术栈覆盖：
+首批技术栈覆盖以两个场景的主流生态为准：

 - Python：Django、FastAPI、Wagtail
- TypeScript：Next.js、NestJS
+- TypeScript：Next.js
 - PHP：Laravel
- Go：API 服务
- Java：Spring Boot
+
+第二批扩展时再覆盖：NestJS、Go API 服务、Spring Boot。

 ## 八、更新节奏

-建议节奏：
+按单人投入校准（与 `content-strategy.md` 发布节奏一致）：

 | 周期 | 工作 |
 | --- | --- |
-| 每周 | 新增 3-5 个候选项目，更新维护状态。 |
-| 每月 | 发布 2-4 篇对比/评测文章。 |
+| 每周 | 新增 2-3 个候选项目，更新维护状态。 |
+| 每两周 | 发布 1 篇对比/评测文章。 |
 | 每季度 | 复查高流量项目评分和推荐结论。 |
 | 每半年 | 清理长期无人维护项目，标记 archived / stale。 |

+M3 闸门通过前，内容库封顶 20 个项目 + 12 篇文章（见 `business-plan-v1.md`）。
+
 ## 九、数据字段建议

 后续录入 Wagtail 时，每个项目至少包含：
@@ -363,14 +364,6 @@ MVP 阶段可以先人工维护，不做自动抓取。
 - 不收录无法明确 license 的项目作为重点推荐。
 - 不为了数量牺牲可信度。

-## 十一、下一步任务建议
+## 十一、下一步任务

-可以同步到 `docs/06-tasks.md` 的后续任务：
-
-```text
-T-105 建立首批骨架项目候选清单
-T-106 完成 SaaS 场景 10 个项目初评
-T-107 完成管理后台场景 10 个项目初评
-T-108 完成 API 服务场景 10 个项目初评
-T-109 完成内容站 / CMS 场景 10 个项目初评
-```
+首批内容库建设任务**已收进 [`../docs/06-tasks.md`](../docs/06-tasks.md) 的 Backlog**（任务状态以看板为唯一权威，本文不再单独维护任务清单）：建立候选清单，完成 SaaS、内容站/CMS 两个场景各 10 个项目初评；管理后台和 API 服务场景在 M3 验证通过后再排期。