diff --git a/AGENTS.md b/AGENTS.md index c1aad7d..e9b958c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,19 +14,26 @@ Skelet 是一个介绍、分类、评测开源项目骨架的网站。目标用 下一步从 [`docs/06-tasks.md`](docs/06-tasks.md) 领取 `T-001`：初始化 Wagtail 项目骨架。 +## 开发环境 + +- 标准开发环境是 WSL2 / Linux，仓库根目录为 `/mnt/d/OPC/skelet`。 +- 所有文档命令统一使用 bash 形态。 +- `init.sh` 是标准启动与验证入口；`init.ps1` 仅作为 Windows 下的可选辅助，允许滞后。 + ## 必读顺序 -每次开始工作前，按顺序读取： +本清单是必读顺序的唯一权威版本，其他文档不重复维护。每次开始工作前，按顺序读取： -1. `README.md`：了解项目定位和当前状态。 -2. `docs/00-ai-start-here.md`：进入 AI 开发流程。 -3. `docs/01-vision.md`：理解为什么做、为谁做、什么不做。 -4. `docs/02-requirements.md`：理解 MVP 功能和验收标准。 -5. `docs/03-tech-stack.md`：确认 Wagtail / Django / Python / SQLite 选型。 -6. `docs/04-architecture.md`：确认系统结构、数据模型、开发顺序。 -7. `docs/05-coding-rules.md`：确认编码硬规则。 -8. `docs/06-tasks.md`：领取唯一任务。 -9. `progress.md` 和 `docs/current-state.md`：恢复历史执行和当前快照。 +1. `docs/00-ai-start-here.md`：进入 AI 开发流程。 +2. `docs/01-vision.md`：理解为什么做、为谁做、什么不做。 +3. `docs/02-requirements.md`：理解 MVP 功能和验收标准。 +4. `docs/03-tech-stack.md`：确认 Wagtail / Django / Python / SQLite 选型。 +5. `docs/04-architecture.md`：确认系统结构、数据模型、评分维度、开发顺序。 +6. `docs/05-coding-rules.md`：确认编码硬规则。 +7. `docs/06-tasks.md`：领取唯一任务。 +8. `progress.md` 和 `docs/current-state.md`：恢复历史执行和当前快照。 + +出现失败模式、做阶段性评审或接入已有代码库时，另查 `docs/90-harness-reference.md`。 ## 工作规则 @@ -41,6 +48,7 @@ Skelet 是一个介绍、分类、评测开源项目骨架的网站。目标用 ## 默认技术边界 - 第一版使用 Wagtail + Django + Python 3.12 + SQLite。 +- 第一版为英文单语言站点（决策依据见 `business/content-strategy.md`）。 - 第一版只需要 Wagtail 管理后台账号，不做前台用户注册。 - 第一版数据库使用 SQLite with JSON1，并启用 WAL 作为上线前建议。 - 第一版部署目标是 2 核 2G VPS。 @@ -48,11 +56,12 @@ Skelet 是一个介绍、分类、评测开源项目骨架的网站。目标用 ## 验证 -当前仓库是文档阶段，生产应用尚不可运行。文档修改后至少检查文件清单，并确认根入口不再误称模板库。 +当前仓库是文档阶段，生产应用尚不可运行。文档修改后至少检查文件清单和 git 状态，并确认根入口不再误称模板库。 -```powershell -Get-ChildItem -Recurse -File +```bash +git status +find . -type f -not -path "./.git/*" ``` -完成 `T-001` 后，必须配置 `init.ps1` / `init.sh` 的真实命令，并以后以脚本作为标准启动与验证入口。 +完成 `T-001` 后，必须配置 `init.sh` 的真实命令（`init.ps1` 可选同步），并以后以脚本作为标准启动与验证入口。 diff --git a/README.md b/README.md index aa1ba6d..a70b72c 100644 --- a/README.md +++ b/README.md @@ -2,59 +2,17 @@ Skelet 是一个面向 AI coding 开发者、独立开发者和小团队的开源项目骨架导航与评测网站。 -第一版目标是把“我应该基于哪个稳定骨架开始新项目”这个决策做清楚：按场景分类，按语言和框架筛选，提供骨架项目详情、AI Coding 友好度评分、适用/不适用场景和基础对比。 +第一版目标是把"我应该基于哪个稳定骨架开始新项目"这个决策做清楚：按场景分类，按语言和框架筛选，提供骨架项目详情、AI Coding 友好度评分、适用/不适用场景和基础对比。第一版为英文单语言站点，主打"AI Coding 友好度"这一差异化角度（决策依据见 [`business/content-strategy.md`](business/content-strategy.md)）。 ## 当前状态 -当前仓库只完成 harness coding 文档初始化，尚未初始化生产代码。 +当前仓库只完成 harness coding 文档初始化，尚未初始化生产代码。下一步任务见 [`docs/06-tasks.md`](docs/06-tasks.md)：先初始化 Wagtail 项目骨架（`T-001`），再实现内容模型和 MVP 页面。 -下一步任务见 [`docs/06-tasks.md`](docs/06-tasks.md)：先初始化 Wagtail 项目骨架，再实现内容模型和 MVP 页面。 +## 入口 -## 技术方案摘要 - -| 维度 | 第一版选择 | -| --- | --- | -| 后端 / CMS | Wagtail | -| Web 框架 | Django | -| Python | 3.12 | -| 数据库 | SQLite with JSON1 | -| 部署目标 | 2 核 2G VPS 可运行 | -| 账号体系 | 第一版只使用 Wagtail 管理后台账号 | -| 前台用户注册 | MVP 不做 | - -详细选型见 [`docs/03-tech-stack.md`](docs/03-tech-stack.md)，架构见 [`docs/04-architecture.md`](docs/04-architecture.md)。 - -## 文档入口 - -- [`AGENTS.md`](AGENTS.md)：Codex / 通用 AI coding agent 仓库级入口。 -- [`CLAUDE.md`](CLAUDE.md)：Claude Code 薄入口。 -- [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)：每轮 AI 开发入口。 -- [`docs/01-vision.md`](docs/01-vision.md)：项目愿景和非目标。 -- [`docs/02-requirements.md`](docs/02-requirements.md)：MVP 需求与验收标准。 -- [`docs/03-tech-stack.md`](docs/03-tech-stack.md)：技术栈、运行命令、依赖纪律。 -- [`docs/04-architecture.md`](docs/04-architecture.md)：系统结构、数据模型、开发顺序。 -- [`docs/05-coding-rules.md`](docs/05-coding-rules.md)：AI 编码硬规则。 -- [`docs/06-tasks.md`](docs/06-tasks.md)：任务看板。 -- [`progress.md`](progress.md)：执行历史流水。 -- [`docs/current-state.md`](docs/current-state.md)：当前实现状态快照。 -- [`business/`](business/)：商业计划书、商业模式、市场分析和增长方案。 - -## 开发原则 - -- 先内容闭环，再商业化。 -- 先场景分类，再语言筛选。 -- 先 Wagtail + SQLite 上线验证，再按需要迁移 PostgreSQL。 -- 第一版不做用户注册、评论、收藏、付费会员和复杂搜索。 -- 每轮 AI coding 只领取一个任务，完成后更新任务状态、进度和当前状态。 - -## 标准开工方式 - -生产代码尚未初始化，因此根目录 `init.ps1` / `init.sh` 仍保留模板占位命令。完成 `T-001` 后必须替换脚本顶部安装、验证和启动命令，并同步更新： - -- [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) -- [`docs/03-tech-stack.md`](docs/03-tech-stack.md) -- [`docs/05-coding-rules.md`](docs/05-coding-rules.md) -- [`docs/current-state.md`](docs/current-state.md) - -在此之前，任何 agent 不得宣称项目“可运行”。 +- [`AGENTS.md`](AGENTS.md)：所有 AI coding agent 的**唯一权威入口**——项目定位、必读顺序、工作规则、技术边界、开发环境和验证方式统一维护在这里。 +- [`CLAUDE.md`](CLAUDE.md)：Claude Code 薄入口，指向 `AGENTS.md`。 +- [`docs/README.md`](docs/README.md)：全部产品与工程文档导航。 +- [`business/`](business/)：商业计划、内容策略、变现方案、竞品分析。 +技术选型摘要、开发原则和开工方式不在本文重复维护，以 `AGENTS.md` 和 `docs/` 为准。 diff --git a/business/README.md b/business/README.md index 75ba31d..a0725eb 100644 --- a/business/README.md +++ b/business/README.md @@ -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)。 diff --git a/business/business-plan-v1.md b/business/business-plan-v1.md index 9d5eaac..73399ae 100644 --- a/business/business-plan-v1.md +++ b/business/business-plan-v1.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`） | ## 十三、第一版执行重点 diff --git a/business/competitor-analysis.md b/business/competitor-analysis.md index b7ca3d7..13a3c9d 100644 --- a/business/competitor-analysis.md +++ b/business/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 友好模板。 | diff --git a/business/content-strategy.md b/business/content-strategy.md index 6380554..5ce9035 100644 --- a/business/content-strategy.md +++ b/business/content-strategy.md @@ -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 项目策略。 ## 十、指标 diff --git a/business/monetization.md b/business/monetization.md index f43d58b..f5f8abf 100644 --- a/business/monetization.md +++ b/business/monetization.md @@ -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 做准备。 - 商业规则写清楚，避免后续损害信任。 diff --git a/business/research-sourcing-strategy.md b/business/research-sourcing-strategy.md index 9c7bf9d..f909618 100644 --- a/business/research-sourcing-strategy.md +++ b/business/research-sourcing-strategy.md @@ -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 验证通过后再排期。 diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index ac9da78..c28730d 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -1,48 +1,16 @@ # AI 开发入口 -> 给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。 - -## 一句话定位 - -Skelet 是面向 AI coding 开发者的开源项目骨架导航与评测网站。 - -第一版 MVP 只做：场景分类、语言 / 框架筛选、骨架项目详情、AI Coding 友好度评分、基础搜索和后台内容维护。 - -## 必读顺序 - -每次开始写代码前，按这个顺序建立上下文： - -1. [`../AGENTS.md`](../AGENTS.md)：仓库级规则。 -2. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。 -3. [`02-requirements.md`](02-requirements.md)：MVP 要什么、怎么算达成。 -4. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型。 -5. [`04-architecture.md`](04-architecture.md)：系统结构、职责划分、数据模型和关键难点。 -6. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。 -7. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。 -8. [`../progress.md`](../progress.md)：历史执行记录、验证结果、阻塞点和关键决策。 -9. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。 +> 给 AI coding agent 的每轮开工流程。项目定位、必读顺序、工作规则、技术边界的唯一权威版本在 [`../AGENTS.md`](../AGENTS.md)，本文不重复；硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。 ## 固定开工流程 -1. `pwd`：确认在 `D:\OPC\skelet`。 +1. `pwd`：确认在仓库根目录（标准开发环境为 WSL/Linux，路径 `/mnt/d/OPC/skelet`）。 2. 读 [`../progress.md`](../progress.md) 和 [`current-state.md`](current-state.md)。 -3. 如果是 git 仓库，运行 `git log --oneline -5`；当前阶段尚未初始化 git 时记录事实即可。 -4. 如果 `init.ps1` / `init.sh` 已配置，运行标准验证；如果脚本仍是占位，先完成 `T-001`。 +3. 运行 `git log --oneline -5`，了解最近提交。 +4. 如果 `init.sh` 已配置真实命令，运行标准验证；如果脚本仍是占位，先完成 `T-001`。 5. 如果基线已坏，先修基线，不在坏的起点上叠新功能。 6. 基线绿了，再从 [`06-tasks.md`](06-tasks.md) 领取唯一任务。 -## 当前阶段 - -当前项目处于：MVP 起步前的 harness 文档初始化阶段。 - -优先路径： - -1. Phase 0：初始化 Wagtail 项目骨架和可运行基线。 -2. Phase 1：建立内容模型和后台维护流程。 -3. Phase 2：实现前台浏览、筛选、详情、评分展示。 -4. Phase 3：完善搜索、SEO、sitemap、部署说明。 -5. Phase 4：上线前验收、备份、SQLite WAL、迁移 PostgreSQL 的触发条件。 - ## 领取任务规则 - 只领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。 @@ -55,22 +23,7 @@ Skelet 是面向 AI coding 开发者的开源项目骨架导航与评测网站 ## MVP 边界 -MVP 只做： - -- 按场景展示骨架项目。 -- 按语言、框架、数据库、AI 友好度筛选。 -- 骨架详情页展示适合场景、技术栈、成熟度、维护状态、功能清单、AI Coding 友好度和推荐理由。 -- 后台可以维护项目、分类、标签、评分和文章。 -- 基础 SEO、站点地图、公开页面可被搜索引擎抓取。 - -MVP 不做： - -- 前台用户注册、登录、收藏、评论。 -- 付费会员、支付、赞助位后台结算。 -- 自动抓取 GitHub 数据。 -- 复杂全文搜索引擎，如 Elasticsearch。 -- 多语言站点。 -- PostgreSQL 生产化迁移，除非 SQLite 触发迁移条件。 +MVP 功能范围以 [`02-requirements.md`](02-requirements.md) 为唯一权威，本文不重复清单。一句话版本：只做场景分类、筛选、详情页、文章、后台维护和基础 SEO；不做用户系统、支付、自动抓取、复杂搜索、多语言。 ## 事实来源 @@ -78,7 +31,7 @@ MVP 不做： - `docs/02-requirements.md` 的 MVP 需求与验收标准。 - `docs/03-tech-stack.md` 的技术选型。 -- `docs/04-architecture.md` 的数据模型和模块边界。 +- `docs/04-architecture.md` 的数据模型、评分维度和模块边界。 - `docs/api.md` 的公开接口和后台边界。 - 未来代码中的 Wagtail models、migrations、templates 和 tests。 @@ -88,11 +41,11 @@ MVP 不做： 生产代码尚未初始化。完成 `T-001` 后，将以下目标命令替换为真实可运行命令： -```powershell -python -m venv .venv -.\.venv\Scripts\python -m pip install -r requirements.txt -.\.venv\Scripts\python manage.py migrate -.\.venv\Scripts\python manage.py runserver +```bash +python3 -m venv .venv +.venv/bin/pip install -r requirements.txt +.venv/bin/python manage.py migrate +.venv/bin/python manage.py runserver ``` -T-001 完成后，必须同步更新 `init.ps1`、`init.sh`、`03-tech-stack.md`、`05-coding-rules.md` 和 `current-state.md`。 +`T-001` 完成后，必须同步更新 `init.sh`（`init.ps1` 可选）、`03-tech-stack.md`、`05-coding-rules.md` 和 `current-state.md`。 diff --git a/docs/02-requirements.md b/docs/02-requirements.md index aa74c9d..139ac6e 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -71,6 +71,8 @@ | 暂不支持 | 用户注册、收藏、评论、支付、自动抓取、复杂搜索、多语言 | | 数据库 | 开发和第一版上线使用 SQLite with JSON1 | | Python | Python 3.12 | +| 站点语言 | 第一版为英文单语言站点，主攻"AI Coding 友好度"角度关键词；中文站作为后续扩展评估（见 `../business/content-strategy.md`） | +| Newsletter | MVP 可放**外部托管**的订阅链接（如 Buttondown，纯外链、无自建后端）；完整 Newsletter 功能仍在 V2 | ## 七、待确认 / 风险点 diff --git a/docs/03-tech-stack.md b/docs/03-tech-stack.md index e5c0649..90c0406 100644 --- a/docs/03-tech-stack.md +++ b/docs/03-tech-stack.md @@ -17,6 +17,8 @@ | 媒体存储 | 本地 media 目录 | 已定 | 2 核 2G VPS 第一版足够；后续可迁移 S3/R2/OSS。 | | 部署方式 | 单 VPS，Gunicorn + Nginx | 待实现 | 面向 2 核 2G VPS；先不引入 Docker 作为必需项。 | | 测试 | Django test / pytest 待定 | 待定 | T-001 初始化后以项目实际生成结构为准。 | +| 开发环境 | WSL2 / Linux + bash | 已定 | 仓库根目录 `/mnt/d/OPC/skelet`；`init.sh` 为标准入口，`init.ps1` 可选。 | +| 访问统计 | Plausible / Umami 或等价轻量方案 | 待实现 | 上线前接入（任务 T-305）；自然搜索和外链点击是 M3/M4 商业验证的前置数据。 | ## 二、决策记录与演进 @@ -35,12 +37,12 @@ | 用途 | 命令 | | --- | --- | -| 创建虚拟环境 | `python -m venv .venv` | -| 安装依赖 | `.\.venv\Scripts\python -m pip install -r requirements.txt` | -| 数据库迁移 | `.\.venv\Scripts\python manage.py migrate` | -| 创建管理员 | `.\.venv\Scripts\python manage.py createsuperuser` | -| 本地开发 | `.\.venv\Scripts\python manage.py runserver` | -| 测试 | `.\.venv\Scripts\python manage.py test` | +| 创建虚拟环境 | `python3 -m venv .venv` | +| 安装依赖 | `.venv/bin/pip install -r requirements.txt` | +| 数据库迁移 | `.venv/bin/python manage.py migrate` | +| 创建管理员 | `.venv/bin/python manage.py createsuperuser` | +| 本地开发 | `.venv/bin/python manage.py runserver` | +| 测试 | `.venv/bin/python manage.py test` | ## 四、SQLite 上线纪律 diff --git a/docs/04-architecture.md b/docs/04-architecture.md index 66bb190..95d8b76 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -86,25 +86,32 @@ SQLite db.sqlite3 | `github_url` | URL | GitHub 地址。 | | `official_url` | URL，可空 | 官网或文档。 | | `license_name` | Char | 开源协议。 | -| `scenario` | relation | 适合场景。 | +| `scenarios` | 多对多 | 适合场景。一个骨架常同时适合多个场景（如 SaaS 和管理后台），必须按多对多实现，避免上线后再迁移。 | | `languages` | 多选 | 使用语言。 | | `frameworks` | 多选 | 使用框架。 | | `databases` | 多选 | 支持数据库。 | | `features` | 多选 | 功能标签。 | | `maturity` | Choice | experimental / stable / mature。 | | `maintenance_status` | Choice | active / slow / unknown / archived。 | -| `ai_friendliness_score` | Integer 0-100 | 总分。 | -| `docs_score` | Integer 0-5 | 文档清晰度。 | | `structure_score` | Integer 0-5 | 目录结构清晰度。 | +| `docs_score` | Integer 0-5 | 文档完整度。 | | `tests_score` | Integer 0-5 | 测试可用性。 | | `example_score` | Integer 0-5 | 示例模块完整度。 | | `dependency_score` | Integer 0-5 | 依赖克制度。 | +| `incremental_score` | Integer 0-5 | 增量开发难度（agent 在既有模式中添加功能是否有清晰落点；含任务切片友好度）。 | | `recommended_for` | RichText / StreamField | 适合什么情况。 | | `not_recommended_for` | RichText / StreamField | 不适合什么情况。 | | `review_notes` | RichText / StreamField | 编辑评测。 | | `is_featured` | Boolean | 是否首页推荐。 | | `is_sponsored` | Boolean | 是否赞助展示，必须前台标识。 | +**评分模型纪律（唯一权威定义）**： + +- AI Coding 友好度评分维度以上表 6 个 0-5 分项为唯一权威：目录结构、文档完整度、测试可用性、示例模块、依赖克制度、增量开发难度。 +- **总分不单独录入**，由 6 个分项计算得出（总和 0-30，前台可换算为百分制展示），用模型 property 或注解实现，避免人工维护时总分和分项对不上。 +- `business/` 下的文档引用本节，不得自行维护另一份维度清单。 +- 每个项目除分数外必须有一句评语：为什么适合 / 不适合 AI coding。 + ### 3.4 URL 与筛选 筛选条件必须可以通过 URL 表达，便于 SEO 和分享： diff --git a/docs/05-coding-rules.md b/docs/05-coding-rules.md index ce5b208..616ba73 100644 --- a/docs/05-coding-rules.md +++ b/docs/05-coding-rules.md @@ -57,12 +57,12 @@ ## 7. 测试与验证 -生产代码尚未初始化。完成 T-001 后，把真实命令填入这里，并同步 `init.ps1` / `init.sh`： +生产代码尚未初始化。完成 T-001 后，把真实命令填入这里，并同步 `init.sh`（`init.ps1` 可选）： -```powershell +```bash # 目标形态 -.\.venv\Scripts\python manage.py check -.\.venv\Scripts\python manage.py test +.venv/bin/python manage.py check +.venv/bin/python manage.py test ``` 完成前至少检查： diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 4b71537..12e7296 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -52,10 +52,13 @@ | T-301 | 补 SEO 基础 | T-205, T-206 | 核心页面有 title、description、canonical 或等价设置；sitemap 可用 | TODO | | T-302 | 补部署文档 | T-301 | 2 核 2G VPS 上 Gunicorn + Nginx + SQLite 的部署步骤清楚 | TODO | | T-303 | SQLite 上线检查 | T-302 | JSON1 验证、WAL 启用、备份策略和 PostgreSQL 迁移触发条件已记录 | TODO | -| T-304 | MVP 完整验收 | T-303 | `02-requirements.md` 的 P0 验收全部通过，验证命令和结果写入 `progress.md` | TODO | +| T-305 | 接入轻量访问统计与外链点击记录 | T-301 | Plausible / Umami 或等价方案接入；外部链接点击可统计；不引入重量级分析 SDK；这是里程碑 M3（SEO 验证）和 M4（Affiliate）的数据前置 | TODO | +| T-304 | MVP 完整验收 | T-303, T-305 | `02-requirements.md` 的 P0 验收全部通过，验证命令和结果写入 `progress.md` | TODO | ## Backlog +- 首批内容库建设（原 `business/research-sourcing-strategy.md` 建议的 T-105~T-109，收敛为先做 2 个场景）：建立候选清单，完成 SaaS、内容站/CMS 两个场景各 10 个项目的初评；管理后台和 API 服务场景在 M3 验证通过后再扩展。 +- llms.txt 与项目数据 JSON 导出：面向 LLM / agent 的可引用性，成本低且与目标用户获取路径高度对齐（见 `business/competitor-analysis.md` "直接问 AI"一节）。 - 用户提交骨架项目并后台审核。 - Newsletter 订阅。 - Affiliate 链接管理。 diff --git a/docs/90-harness-reference.md b/docs/90-harness-reference.md new file mode 100644 index 0000000..a348071 --- /dev/null +++ b/docs/90-harness-reference.md @@ -0,0 +1,112 @@ +# Harness 参考（方法对照 · 评审 · 健康度 · 接入清单） + +> 本文合并原 `method-map.md`、`evaluator-rubric.md`、`quality-document.md`、`adoption-checklist.md` 四个元文档，移出每轮必读链路。 +> 日常开工只需 [`../AGENTS.md`](../AGENTS.md) → [`00-ai-start-here.md`](00-ai-start-here.md)。出现失败模式、做阶段性评审或接入已有代码库时再查本文。 + +## 一、失败模式 → 首要修复 + +出问题时先查这张表，对症补对应工件，不要把更多规则一股脑堆进入口文件。 + +| 失败模式 | 实际表现 | 首要修复 | 主要工件 | +| --- | --- | --- | --- | +| 新会话摸黑 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为唯一事实来源 | [`current-state.md`](current-state.md) + [`../progress.md`](../progress.md) | +| 启动脆弱 | 每轮会话都要重新学怎么启动、装依赖、跑测试 | 统一启动与验证路径 | [`../init.sh`](../init.sh) | +| 范围蔓延 | 一次启动多个任务，最后没有一个完整收尾 | 限制当前活跃范围，一轮只做一个任务 | [`06-tasks.md`](06-tasks.md) | +| 提前宣布完成 | 代码改了就说"完成了"，但没有可运行证据 | 把完成绑定到验证证据 | [`06-tasks.md`](06-tasks.md) + [`clean-state-checklist.md`](clean-state-checklist.md) | +| 交接薄弱 | 下一轮看不出哪里可用、哪里坏了、接下来做什么 | 每轮留下明确的当前快照和下一步 | [`current-state.md`](current-state.md) | +| 评审主观 | 质量判断靠感觉，agent 容易自我说服通过 | 用固定维度做评分 | 本文第二节 | +| 代码库悄悄退化 | 几轮会话后代码越来越难审、边界越来越糊 | 定期给代码库健康度打分 | 本文第三节 | +| 文档堆叠失控 | 入口文件越来越长，"每次失败加一句" | 渐进披露，入口保持薄；同一个事实只维护一份 | [`../AGENTS.md`](../AGENTS.md) + 拆分到具体文档 | + +使用原则： + +- 优先补最能直接消除当前失败模式的那**一个**工件，不要一次铺开全部。 +- 同一个事实只维护一份，避免多个文件互相打架。 +- 修复落地的同一轮会话里，就把对应工件更新掉。 + +## 二、单轮输出评审表 + +评的是**单次输出质量**；代码库长期健康度见第三节。六个维度，每个 0-2 分（0 不满足 · 1 部分满足 · 2 满足）。 + +| 维度 | 问题 | 分数 (0-2) | 备注 | +| --- | --- | --- | --- | +| 正确性 | 实现出来的行为是否符合目标功能 / 验收标准？ | | | +| 验证 | 要求的检查是否真的跑过，并在 `../progress.md` 留下证据？ | | | +| 范围纪律 | 这一轮是否基本保持在选定的单个任务范围内？ | | | +| 可靠性 | 结果是否能在重启或重跑后继续工作？ | | | +| 可维护性 | 代码和文档是否清楚到足以交给下一轮会话？ | | | +| 交接准备度 | 新会话是否能只靠仓库内文件继续推进？ | | | + +结论三选一：**Accept**（达标）· **Revise**（列出必须补的修复）· **Block**（列出阻塞项）。 + +校准提示：agent 自评容易自我说服通过。前几次评审需要把每个维度"什么算 2 分 / 什么算 0 分"落到本项目的真实验收标准上，并在 `../progress.md` 记录校准调整，直到评审判断和人工判断基本一致。 + +## 三、代码库健康度追踪 + +- 开始会话前：读它，了解代码库当前哪里最弱。 +- 会话结束后：如有实质变化则更新评级。 +- 长期：对比不同时间点的快照，看哪些改动真正改善了健康度。 + +评级标准：**A** 验证全部通过、结构干净、测试稳定 · **B** 验证通过、有少量缺口 · **C** 部分可用、有已知缺口 · **D** 不可用或重大结构问题。 + +### 产品领域 + +| 领域 | 评级 | 验证状态 | Agent 可读性 | 测试稳定性 | 关键缺口 | 上次更新 | +|------|------|---------|-------------|-----------|---------|---------| +| Harness 文档 | B | 文档已初始化并完成瘦身合并 | 高 | 不适用 | 生产代码未初始化 | 2026-07-06 | +| 内容目录 MVP | D | 未实现 | 中 | 无测试 | Wagtail 项目未初始化 | 2026-07-06 | +| 筛选与搜索 | D | 未实现 | 中 | 无测试 | 依赖内容模型和列表页 | 2026-07-06 | +| 后台内容管理 | D | 未实现 | 中 | 无测试 | 依赖 Wagtail 初始化和模型 | 2026-07-06 | +| SEO 与部署 | D | 未实现 | 中 | 无测试 | 依赖前台页面和部署配置 | 2026-07-06 | + +### 架构层 + +| 层级 | 评级 | 边界执行 | Agent 可读性 | 关键缺口 | 上次更新 | +|------|------|---------|-------------|---------|---------| +| Wagtail / Django 应用层 | D | 尚无代码 | 中 | 未初始化项目 | 2026-07-06 | +| 模板层 | D | 尚无代码 | 中 | 未建立 base 和页面模板 | 2026-07-06 | +| 数据 / 存储层 | D | 尚无代码 | 中 | SQLite、迁移和模型未建立 | 2026-07-06 | +| 部署层 | D | 尚无代码 | 中 | Gunicorn、Nginx、备份和 WAL 未配置 | 2026-07-06 | + +### 变更历史 + +#### 2026-07-06（第二次） + +- 变更内容：harness 文档瘦身。合并四个元文档为本文；统一入口为 `AGENTS.md`；修正 git 状态等过期事实；评分维度收敛到 `04-architecture.md` 唯一定义；开发环境定为 WSL/Linux。 +- 提升：重复维护点减少，文档漂移风险下降。 +- 下降：无。 + +#### 2026-07-06 + +- 变更内容：建立 harness coding 文档基线。 +- 提升：项目目标、MVP 范围、技术栈、架构、任务顺序和当前状态已写入仓库。 +- 新发现的缺口：生产代码尚未初始化，无法运行 Wagtail 验证。 + +## 四、已有代码接入 / 恢复清单 + +适用场景：已初始化 Wagtail 但下一轮 agent 不清楚真实启动命令；文档、代码和可运行状态出现偏差；把本项目 harness 文档迁移到其他代码库。 + +最小接入文件：`AGENTS.md`、`CLAUDE.md`、`docs/00-ai-start-here.md`、`docs/05-coding-rules.md`、`docs/06-tasks.md`、`docs/current-state.md`、`progress.md`、`init.sh`。 + +恢复步骤： + +1. 确认在仓库根目录（WSL 下为 `/mnt/d/OPC/skelet`）。 +2. 读取 `AGENTS.md`、`docs/00-ai-start-here.md`、`docs/current-state.md`。 +3. 查看 `docs/06-tasks.md`，领取第一个 `TODO` 且依赖均为 `DONE` 的任务。 +4. 生产代码尚未初始化时先做 `T-001`，不要提前实现业务页面。 +5. 初始化 Wagtail 后，立刻更新 `init.sh`、`docs/03-tech-stack.md`、`docs/current-state.md` 中的真实命令。 +6. 运行标准验证，把结果追加到 `progress.md`；验证失败时先修基线，不做新功能。 + +代码现实与文档冲突时： + +- 以当前可运行代码和真实验证结果为事实起点。 +- 文档描述旧功能但代码不存在：先把差异记录到 `current-state.md`，不要直接补实现。 +- 代码已有行为但文档没写：先补 `02-requirements.md`、`04-architecture.md`、`api.md` 或 `routes.md`，再改代码。 +- 命令不可运行时不要标记任务完成；在 `progress.md` 记录失败命令和错误摘要。 + +不建议做的事： + +- 不要一次性实现首页、模型、筛选、SEO 和部署。 +- 不要把聊天记录当事实来源。 +- 不要为了让验证通过而降低测试或验收标准。 +- 不要在接入 harness 的同一轮顺手重构无关代码。 diff --git a/docs/README.md b/docs/README.md index bbd2a10..f8fa61c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,31 +1,26 @@ # 项目文档导航 -## 一句话定位 - -Skelet 是一个面向 AI coding 开发者、独立开发者和小团队的开源项目骨架导航与评测网站，用于解决“从哪个稳定骨架开始新项目更省 token、更省时间、更不容易跑偏”的决策问题，第一版先完成“浏览分类 -> 筛选骨架 -> 查看详情与评分 -> 形成选型判断”的 MVP 闭环。 +项目定位、必读顺序和工作规则的唯一权威入口是 [`../AGENTS.md`](../AGENTS.md)，本文只做文档导航，不重复维护这些内容。 ## 文档导航 -- [`../AGENTS.md`](../AGENTS.md)：Codex / 通用 AI coding agent 的仓库级入口。 -- [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的薄入口，具体规则以 `AGENTS.md` 为准。 +- [`../AGENTS.md`](../AGENTS.md)：所有 AI coding agent 的仓库级权威入口。 +- [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 薄入口，指向 `AGENTS.md`。 - [`../tasks.md`](../tasks.md)：根目录任务入口，指向 `06-tasks.md`。 - [`../progress.md`](../progress.md)：执行历史流水，只追加记录任务执行、验证、阻塞和决策。 -- [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。 +- [AI 开发入口](00-ai-start-here.md)：每轮开工流程和任务领取规则。 - [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。 -- [需求](02-requirements.md)：MVP 要什么、怎么算达成。 -- [技术栈](03-tech-stack.md)：Wagtail / Django / Python / SQLite 等技术选型和运行命令。 -- [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。 +- [需求](02-requirements.md)：MVP 要什么、怎么算达成、范围边界决策。 +- [技术栈](03-tech-stack.md)：技术选型、运行命令、依赖纪律。 +- [架构设计](04-architecture.md)：系统结构、数据模型（含 AI 友好度评分维度的**唯一权威定义**）、关键风险、开发顺序。 - [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。 -- [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个。 -- [API 合约](api.md)：MVP 不提供公开 API，记录 Wagtail 路由、后续 API 边界。 +- [任务看板](06-tasks.md)：按依赖拆分的小任务，每轮只做一个。 +- [API 合约](api.md)：MVP 不提供公开 API，记录 Wagtail 路由和后续 API 边界。 - [路由与页面结构](routes.md)：前台页面、后台路由、页面职责和组件归属。 - [当前实现状态](current-state.md)：当前仓库现实状态、可运行命令和下一步任务。 -- [收尾检查清单](clean-state-checklist.md)：会话结束前逐项检查，保证下一轮无需人工修复即可继续。 -- [已有项目接入清单](adoption-checklist.md)：已有代码库接入 harness 文档时使用，本项目当前是空项目初始化。 -- [方法对照表](method-map.md)：失败模式与首要修复工件。 -- [评审评分表](evaluator-rubric.md)：单次会话输出质量评审。 -- [质量文档](quality-document.md)：代码库长期健康度追踪。 -- [`../init.sh`](../init.sh) / [`../init.ps1`](../init.ps1)：标准启动与验证入口脚本；生产代码初始化后再替换真实命令。 +- [收尾检查清单](clean-state-checklist.md)：会话结束前逐项检查。 +- [Harness 参考](90-harness-reference.md)：失败模式对照、单轮评审表、健康度追踪、已有代码接入清单。**按需查阅，不在每轮必读链路。** +- [`../init.sh`](../init.sh)：标准启动与验证入口脚本（`init.ps1` 为 Windows 可选辅助）。 ## 任务 / 进度 / 当前状态 @@ -35,7 +30,4 @@ Skelet 是一个面向 AI coding 开发者、独立开发者和小团队的开 ## 维护原则 -- 需求变化先改 `02-requirements.md`，再改代码。 -- 技术方案变化先改 `03-tech-stack.md` 和 `04-architecture.md`，再改代码。 -- 代码现实变化后同步 `current-state.md` 和 `06-tasks.md`，执行过程追加到 `../progress.md`。 -- MVP 范围外的商业化、会员、用户投稿、复杂搜索只进入 Backlog，不提前实现。 +见 [`../AGENTS.md`](../AGENTS.md) 的工作规则：需求变化先改 `02-requirements.md`，技术方案变化先改 `03-tech-stack.md` 和 `04-architecture.md`，代码现实变化后同步 `current-state.md`、`06-tasks.md` 和 `../progress.md`。 diff --git a/docs/adoption-checklist.md b/docs/adoption-checklist.md deleted file mode 100644 index 861fc47..0000000 --- a/docs/adoption-checklist.md +++ /dev/null @@ -1,46 +0,0 @@ -# 已有项目接入 / 恢复清单 - -> 本项目当前是空目录起步，已完成 harness 文档初始化。本文用于两种情况：后续已经有 Wagtail 代码后恢复上下文，或把本项目文档接入到另一个已有代码库。 - -## 适用场景 - -- 已经初始化 Wagtail，但下一轮 agent 不清楚真实启动命令。 -- 文档、代码和当前可运行状态出现偏差。 -- 想把 Skelet 的 harness 文档迁移到另一个骨架介绍网站项目。 - -## 最小接入文件 - -| 文件 | 作用 | -| --- | --- | -| `AGENTS.md` | 仓库级 agent 入口和总规则。 | -| `CLAUDE.md` | Claude Code 薄入口，指向 `AGENTS.md`。 | -| `docs/00-ai-start-here.md` | 每轮开工流程。 | -| `docs/05-coding-rules.md` | 编码纪律和验证底线。 | -| `docs/06-tasks.md` | 任务看板。 | -| `docs/current-state.md` | 当前实现状态快照。 | -| `progress.md` | 只追加的执行流水。 | -| `init.sh` 或 `init.ps1` | 标准启动与验证入口，按操作系统二选一。 | - -## 当前项目恢复步骤 - -1. 确认仓库根目录是 `D:\OPC\skelet`。 -2. 读取 `AGENTS.md`、`docs/00-ai-start-here.md`、`docs/current-state.md`。 -3. 查看 `docs/06-tasks.md`，领取第一个 `TODO` 且依赖均为 `DONE` 的任务。 -4. 如果生产代码尚未初始化，先做 `T-001`，不要提前实现业务页面。 -5. 初始化 Wagtail 后，立刻更新 `init.ps1`、`init.sh`、`docs/03-tech-stack.md`、`docs/current-state.md` 中的真实命令。 -6. 运行标准验证，把结果追加到 `progress.md`。 -7. 如果验证失败，第一轮任务应先修基线，不做新功能。 - -## 代码现实与文档冲突时 - -- 以当前可运行代码和真实验证结果为事实起点。 -- 文档描述旧功能但代码不存在时，先把差异记录到 `current-state.md`，不要直接补实现。 -- 代码已有行为但文档没写时，先补 `02-requirements.md`、`04-architecture.md`、`api.md` 或 `routes.md`，再继续修改代码。 -- 命令不可运行时，不要标记任务完成；在 `progress.md` 记录失败命令和错误摘要。 - -## 不建议做的事 - -- 不要一次性实现首页、模型、筛选、SEO 和部署。 -- 不要把聊天记录当事实来源。 -- 不要为了让验证通过而降低测试或验收标准。 -- 不要在接入 harness 的同一轮顺手重构无关代码。 diff --git a/docs/current-state.md b/docs/current-state.md index 078c3bf..bf4462a 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -11,12 +11,14 @@ ## 当前快照 - 日期：2026-07-06 -- 阶段：MVP 起步前，harness 文档已初始化 -- 技术栈：目标为 Wagtail + Django + Python 3.12 + SQLite +- 阶段：MVP 起步前，harness 文档已初始化并完成瘦身（元文档合并为 `90-harness-reference.md`，入口统一为 `AGENTS.md`） +- 开发环境：WSL2 / Linux，仓库根目录 `/mnt/d/OPC/skelet`，bash 为标准命令形态 +- git：已初始化，主分支 `main` +- 技术栈：目标为 Wagtail + Django + Python 3.12 + SQLite；第一版英文单语言站点 - 生产代码：尚未初始化 - 测试：尚未初始化 - 数据：尚未建立 seed 数据；未来通过 Wagtail 后台录入首批项目 -- 标准启动路径：`init.ps1` / `init.sh` 尚未配置真实命令 +- 标准启动路径：`init.sh` 尚未配置真实命令（`init.ps1` 为可选辅助） - 标准验证路径：生产代码初始化后补齐 - 当前 blocker：未初始化 Wagtail 项目骨架；下一步执行 `T-001` @@ -43,18 +45,19 @@ ## 当前可运行内容 -```powershell +```bash # 当前只能做文档检查 -Get-ChildItem -Recurse -File +git status +find . -type f -not -path "./.git/*" ``` 生产应用命令待 T-001 初始化后补齐： -```powershell +```bash # 目标形态 -.\.venv\Scripts\python manage.py check -.\.venv\Scripts\python manage.py test -.\.venv\Scripts\python manage.py runserver +.venv/bin/python manage.py check +.venv/bin/python manage.py test +.venv/bin/python manage.py runserver ``` ## 开始编码前检查 diff --git a/docs/evaluator-rubric.md b/docs/evaluator-rubric.md deleted file mode 100644 index e46d263..0000000 --- a/docs/evaluator-rubric.md +++ /dev/null @@ -1,43 +0,0 @@ -# 评审评分表 - -> 在一轮（或几轮）会话实现完成后、正式验收前，用这张表做一次结构化评审，回答"这轮 agent 做得好不好"。 -> 它评的是**单次输出质量**；代码库长期健康度见 [`quality-document.md`](quality-document.md)。 - -## 评分维度 - -六个维度，每个 0-2 分（0 不满足 · 1 部分满足 · 2 满足）。 - -| 维度 | 问题 | 分数 (0-2) | 备注 | -| --- | --- | --- | --- | -| 正确性 | 实现出来的行为是否符合目标功能 / 验收标准？ | | | -| 验证 | 要求的检查是否真的跑过，并在 `../progress.md` 留下证据？ | | | -| 范围纪律 | 这一轮是否基本保持在选定的单个任务范围内？ | | | -| 可靠性 | 结果是否能在重启或重跑后继续工作？ | | | -| 可维护性 | 代码和文档是否清楚到足以交给下一轮会话？ | | | -| 交接准备度 | 新会话是否能只靠仓库内文件继续推进？ | | | - -## 结论 - -从下面三选一： - -- **Accept** — 达标，可验收。 -- **Revise** — 需要修补才能接受（列出必须补的修复）。 -- **Block** — 有根本性问题，需要先解决（列出阻塞项）。 - -## 后续动作 - -- 缺失的证据： -- 必须补的修复： -- 下次复审触发条件： - -## 关于校准（重要） - -开箱即用的 agent 做评审很弱——它会发现问题，然后把自己说服到通过。所以这张表的通过/失败标准需要反复校准到和人工判断一致： - -1. 用本表给一个已完成的任务打分。 -2. 把它的分数和你自己的人工判断对比。 -3. 有分歧的地方，把对应维度的"什么算 2 分 / 什么算 0 分"写得更具体，落到本项目的真实验收标准上。 -4. 对同一个输出重新打分，看是否对齐。 -5. 重复直到评审判断和人工评审基本一致。 - -预计需要 3-5 轮校准。每轮在 `../progress.md` 记录改了什么、为什么改。 diff --git a/docs/method-map.md b/docs/method-map.md deleted file mode 100644 index f2de077..0000000 --- a/docs/method-map.md +++ /dev/null @@ -1,31 +0,0 @@ -# 方法对照表 - -> 把最常见的长时 coding-agent 失败模式，对应到本仓库里最该先补的工件或规则。 -> 出问题时先查这张表，对症补对应工件，不要把更多规则一股脑堆进一个超长入口文件。 - -## 失败模式 → 首要修复 → 工件 - -| 失败模式 | 实际表现 | 首要修复 | 主要工件 | -| --- | --- | --- | --- | -| 新会话摸黑 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为唯一事实来源 | [`current-state.md`](current-state.md) + [`../progress.md`](../progress.md) | -| 启动脆弱 | 每轮会话都要重新学怎么启动、装依赖、跑测试 | 统一启动与验证路径 | [`../init.sh`](../init.sh) / [`../init.ps1`](../init.ps1) | -| 范围蔓延 | 一次启动多个任务，最后没有一个完整收尾 | 限制当前活跃范围，一轮只做一个任务 | [`06-tasks.md`](06-tasks.md) | -| 提前宣布完成 | 代码改了就说"完成了"，但没有可运行证据 | 把完成绑定到验证证据 | [`06-tasks.md`](06-tasks.md)（passing 需证据）+ [`clean-state-checklist.md`](clean-state-checklist.md) | -| 交接薄弱 | 下一轮看不出哪里可用、哪里坏了、接下来做什么 | 每轮留下明确的当前快照和下一步 | [`current-state.md`](current-state.md) | -| 评审主观 | 质量判断靠个人记忆和感觉，agent 容易自我说服通过 | 用固定维度做评分 | [`evaluator-rubric.md`](evaluator-rubric.md) | -| 代码库悄悄退化 | 速度上去了，但几轮会话后代码越来越难审、边界越来越糊 | 定期给代码库健康度打分 | [`quality-document.md`](quality-document.md) | -| 文档堆叠失控 | 入口文件越来越长，"每次失败加一句" | 渐进披露，入口保持薄 | [`00-ai-start-here.md`](00-ai-start-here.md) + 拆分到具体文档 | - -## 使用原则 - -- 优先补最能直接消除当前失败模式的那**一个**工件，不要一次铺开全部。 -- 工件之间用链接互相引用，让全新 agent 不问人也能从一个文件跳到相关规则。 -- 同一个事实只维护一份，避免多个文件互相打架。 -- 修复落地的同一轮会话里，就把对应工件更新掉。 - -## 评审 vs 健康度：两个不同的问题 - -- [`evaluator-rubric.md`](evaluator-rubric.md) 回答：**"这轮 agent 做得好不好？"**（单次输出质量） -- [`quality-document.md`](quality-document.md) 回答：**"这个项目在变强还是变弱？"**（代码库本身质量） - -两者配合：rubric 守住每轮交付，quality document 守住长期趋势。 diff --git a/docs/quality-document.md b/docs/quality-document.md deleted file mode 100644 index debd62a..0000000 --- a/docs/quality-document.md +++ /dev/null @@ -1,45 +0,0 @@ -# 质量文档 - -> 跟踪代码库随时间是变强还是变弱。它评的是代码库本身的质量；单次 agent 输出质量见 [`evaluator-rubric.md`](evaluator-rubric.md)。 - -## 使用时机 - -- 开始会话前：读它，了解代码库当前哪里最弱。 -- 会话结束后：更新评级。 -- 长期：对比不同时间点的快照，看哪些改动真正改善了代码库健康度。 - -## 评级标准 - -- **A**：验证全部通过，结构干净，agent 能读懂，测试稳定。 -- **B**：验证通过，基本干净，可读性或测试覆盖有少量缺口。 -- **C**：部分可用，有已知缺口，部分代码 agent 不容易理解。 -- **D**：不可用，或存在重大结构问题。 - -## 产品领域 - -| 领域 | 评级 | 验证状态 | Agent 可读性 | 测试稳定性 | 关键缺口 | 上次更新 | -|------|------|---------|-------------|-----------|---------|---------| -| Harness 文档 | B | 文档已初始化，待残留占位检查 | 高 | 不适用 | 生产代码未初始化 | 2026-07-06 | -| 内容目录 MVP | D | 未实现 | 中 | 无测试 | Wagtail 项目未初始化 | 2026-07-06 | -| 筛选与搜索 | D | 未实现 | 中 | 无测试 | 依赖内容模型和列表页 | 2026-07-06 | -| 后台内容管理 | D | 未实现 | 中 | 无测试 | 依赖 Wagtail 初始化和模型 | 2026-07-06 | -| SEO 与部署 | D | 未实现 | 中 | 无测试 | 依赖前台页面和部署配置 | 2026-07-06 | - -## 架构层 - -| 层级 | 评级 | 边界执行 | Agent 可读性 | 关键缺口 | 上次更新 | -|------|------|---------|-------------|---------|---------| -| Wagtail / Django 应用层 | D | 尚无代码 | 中 | 未初始化项目 | 2026-07-06 | -| 模板层 | D | 尚无代码 | 中 | 未建立 base 和页面模板 | 2026-07-06 | -| 数据 / 存储层 | D | 尚无代码 | 中 | SQLite、迁移和模型未建立 | 2026-07-06 | -| 部署层 | D | 尚无代码 | 中 | Gunicorn、Nginx、备份和 WAL 未配置 | 2026-07-06 | - -## 变更历史 - -### 2026-07-06 - -- 变更内容：建立 harness coding 文档基线。 -- 提升：项目目标、MVP 范围、技术栈、架构、任务顺序和当前状态已写入仓库。 -- 下降：无。 -- 新发现的缺口：生产代码尚未初始化，无法运行 Wagtail 验证。 -- 已关闭的缺口：从空目录进入开发时缺少 AI agent 入口和任务看板的问题已关闭。 diff --git a/progress.md b/progress.md index 72e671c..b0d7737 100644 --- a/progress.md +++ b/progress.md @@ -37,3 +37,18 @@ - 决策：第一版采用 Wagtail + Django + Python 3.12 + SQLite；先做内容目录和评测闭环，不做前台用户系统、支付、评论、自动抓取和复杂搜索。 - 下一步：T-001 初始化 Wagtail 项目骨架。 +## 2026-07-06 文档审核与优化（harness 文档瘦身 + 商业计划加验证闸门） + +- 状态：DONE +- 变更： + - docs 瘦身：`method-map.md`、`evaluator-rubric.md`、`quality-document.md`、`adoption-checklist.md` 四个元文档合并为 `docs/90-harness-reference.md` 并删除原文件，移出每轮必读链路；`AGENTS.md` 定为唯一权威入口，`README.md`、`docs/README.md`、`docs/00-ai-start-here.md` 删除重复的定位/必读顺序/技术栈内容，改为链接。 + - 纠错：修正 `00-ai-start-here.md` 中"尚未初始化 git"的过期事实；开发环境定为 WSL2/Linux（`/mnt/d/OPC/skelet`），全部文档命令改为 bash 形态，`init.sh` 为标准入口、`init.ps1` 降为可选。 + - 评分模型统一：`04-architecture.md` 定为评分维度唯一权威（6 个 0-5 分项，新增 `incremental_score`，删除独立录入的 0-100 总分，总分改为由分项计算）；`business-plan-v1.md` 和 `research-sourcing-strategy.md` 改为引用。 + - 数据模型：`scenario` 字段明确为多对多（`scenarios`）。 + - 任务看板：新增 T-305（轻量访问统计与外链点击，M3/M4 数据前置，T-304 增加对其依赖）；Backlog 收入首批内容库任务（原 T-105~T-109，收敛为 2 个场景）和 llms.txt/JSON 导出。 + - 商业文档：里程碑加验证闸门和止损线（M2 从 8 场景 50 项目砍到 2 场景 20 项目；M3 定 8 周/12 周复盘线；内容投入封顶 20 项目+12 篇）；定站点语言为英文单语言、主攻"AI Coding 友好度"角度词、头部词只作词根；竞品分析补"直接问 AI"为最大隐性竞品及 llms.txt 借力策略；Newsletter 口径统一为"MVP 外部托管订阅外链、完整功能 V2"；付费价格标注为未验证假设；发布节奏按单人投入下调。 +- 验证：`git status` + `find . -type f -not -path "./.git/*"` 确认文件清单；`grep` 确认仓库内已无对四个被删元文档的引用（progress.md 历史记录除外），无残留 PowerShell 命令（历史记录除外）。 +- 阻塞：无。 +- 决策：第一版英文单语言站点；首批只做 SaaS 和内容站/CMS 两个场景；评分维度以 `docs/04-architecture.md` 为唯一权威；M3 闸门不过不扩内容。 +- 下一步：T-001 初始化 Wagtail 项目骨架。 +