opc/skelet
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation from Claude Code

Browse Source
This commit is contained in:
QiuSW
2026-07-06 11:32:35 +08:00
parent fae7fda88c
commit 53d6430ea0
22 changed files with 345 additions and 423 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+23 -14
View File
@@ -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` 可选同步），并以后以脚本作为标准启动与验证入口。
README.md
+8 -50
View File
@@ -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/` 为准。
business/README.md
+6
View File
@@ -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)。
business/business-plan-v1.md
+18 -20
View File
@@ -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`） |
## 十三、第一版执行重点
business/competitor-analysis.md
+34 -14
View File
@@ -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 友好模板。 |
business/content-strategy.md
+42 -28
View File
@@ -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 项目策略。
## 十、指标
business/monetization.md
+3 -3
View File
@@ -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 做准备。
- 商业规则写清楚，避免后续损害信任。
business/research-sourcing-strategy.md
+19 -26
View File
@@ -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 验证通过后再排期。
docs/00-ai-start-here.md
+12 -59
View File
@@ -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`。
docs/02-requirements.md
+2
View File
@@ -71,6 +71,8 @@
| 暂不支持 | 用户注册、收藏、评论、支付、自动抓取、复杂搜索、多语言 |
| 数据库 | 开发和第一版上线使用 SQLite with JSON1 |
| Python | Python 3.12 |
| 站点语言 | 第一版为英文单语言站点，主攻"AI Coding 友好度"角度关键词；中文站作为后续扩展评估（见 `../business/content-strategy.md`） |
| Newsletter | MVP 可放**外部托管**的订阅链接（如 Buttondown，纯外链、无自建后端）；完整 Newsletter 功能仍在 V2 |
## 七、待确认 / 风险点
docs/03-tech-stack.md
+8 -6
View File
@@ -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 上线纪律
docs/04-architecture.md
+10 -3
View File
@@ -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 和分享：
docs/05-coding-rules.md
+4 -4
View File
@@ -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
```
完成前至少检查：
docs/06-tasks.md
+4 -1
View File
@@ -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 链接管理。
docs/90-harness-reference.md
+112
View File
@@ -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 的同一轮顺手重构无关代码。
docs/README.md
+13 -21
View File
@@ -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`。
docs/adoption-checklist.md
-46
View File
@@ -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 的同一轮顺手重构无关代码。
docs/current-state.md
+12 -9
View File
@@ -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
```
## 开始编码前检查
docs/evaluator-rubric.md
-43
View File
@@ -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` 记录改了什么、为什么改。
docs/method-map.md
-31
View File
@@ -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 守住长期趋势。
docs/quality-document.md
-45
View File
@@ -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 入口和任务看板的问题已关闭。
progress.md
+15
View File
@@ -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 项目骨架。