Add harness coding documentation

docs/00-ai-start-here.md

@@ -0,0 +1,98 @@
+# 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)：当前代码现实、可运行命令、下一步任务。
+
+## 固定开工流程
+
+1. `pwd`：确认在 `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`。
+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` 的任务。
+- 开始前把该任务状态改为 `DOING`。
+- 本轮只完成这一个任务。
+- 验收通过后把状态改为 `DONE`。
+- 完成后把执行记录追加到 [`../progress.md`](../progress.md)，并覆盖更新 [`current-state.md`](current-state.md)。
+- 结束会话前过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)。
+- 做完即停，汇报验证结果。
+
+## MVP 边界
+
+MVP 只做：
+
+- 按场景展示骨架项目。
+- 按语言、框架、数据库、AI 友好度筛选。
+- 骨架详情页展示适合场景、技术栈、成熟度、维护状态、功能清单、AI Coding 友好度和推荐理由。
+- 后台可以维护项目、分类、标签、评分和文章。
+- 基础 SEO、站点地图、公开页面可被搜索引擎抓取。
+
+MVP 不做：
+
+- 前台用户注册、登录、收藏、评论。
+- 付费会员、支付、赞助位后台结算。
+- 自动抓取 GitHub 数据。
+- 复杂全文搜索引擎，如 Elasticsearch。
+- 多语言站点。
+- PostgreSQL 生产化迁移，除非 SQLite 触发迁移条件。
+
+## 事实来源
+
+项目事实只信：
+
+- `docs/02-requirements.md` 的 MVP 需求与验收标准。
+- `docs/03-tech-stack.md` 的技术选型。
+- `docs/04-architecture.md` 的数据模型和模块边界。
+- `docs/api.md` 的公开接口和后台边界。
+- 未来代码中的 Wagtail models、migrations、templates 和 tests。
+
+不要把聊天记录、临时实验目录、未被任务引用的草稿或第三方模板默认示例数据当事实来源。
+
+## 验证命令
+
+生产代码尚未初始化。完成 `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
+```
+
+T-001 完成后，必须同步更新 `init.ps1`、`init.sh`、`03-tech-stack.md`、`05-coding-rules.md` 和 `current-state.md`。

docs/01-vision.md

@@ -0,0 +1,45 @@
+# 项目愿景
+
+## 一、核心目标
+
+Skelet 要解决：AI coding 时代，从零开始写项目既耗 token 又耗时间，开发者需要更快找到适合当前场景的稳定开源骨架。
+
+> 让开发者能够按场景、语言、框架和 AI 友好度选择项目骨架，并获得清晰的“适合 / 不适合 / 为什么”判断。
+
+它不是模板商城，也不是泛泛的 awesome list，而是一个为“新项目启动选型”服务的结构化评测网站。
+
+## 二、目标用户
+
+- 独立开发者：希望快速启动 SaaS、内容站、管理后台、API 服务等项目。
+- 小团队技术负责人：希望给团队选择可长期维护的稳定骨架。
+- AI coding 使用者：希望减少 agent 理解项目结构的 token 和时间消耗。
+- 开源骨架作者：希望让自己的项目被更准确地介绍和比较。
+
+## 三、产品原则
+
+- **场景优先**：主导航按用户要做什么分类，语言和框架作为筛选项。
+- **可信优先**：明确区分编辑推荐、普通收录和赞助展示。
+- **AI 友好优先**：评分重点看目录结构、文档、测试、示例模块、增量开发难度。
+- **小步上线**：第一版先做内容目录和评测闭环，不提前做会员、评论、支付。
+- **可迁移**：第一版 SQLite 可上线，但模型和代码不绑定 SQLite 专属能力，后续可迁移 PostgreSQL。
+- **可维护**：文档、模型、路由、任务拆分必须让后续 agent 能继续接手。
+
+## 四、核心价值主张
+
+| 价值点 | 说明 |
+| --- | --- |
+| 选型更快 | 用户不需要在 GitHub 和搜索引擎里反复比较模板。 |
+| AI coding 更稳 | 推荐的骨架要说明是否适合 agent 增量开发。 |
+| 风险更清楚 | 每个骨架展示不适合场景、维护风险、依赖复杂度。 |
+| 后续可商业化 | 内容信任建立后可扩展 affiliate、赞助、付费数据库和自有模板。 |
+
+## 五、不做什么（非目标）
+
+- 不做第一版前台用户社区。
+- 不做自动生成完整项目代码。
+- 不做谁付费谁排名第一的榜单。
+- 不做复杂 SaaS 会员系统。
+- 不做高并发写入场景。
+- 不做爬虫批量抓取和自动评分，MVP 先人工录入。
+
+MVP 的具体功能范围与验收标准，见 [需求](02-requirements.md)。

docs/02-requirements.md

@@ -0,0 +1,83 @@
+# 需求
+
+> 本文只描述要什么与怎么算达成。技术方案、数据结构、字段定义见 [架构设计](04-architecture.md)。
+
+## 一、业务现状
+
+| 项 | 状态 |
+| --- | --- |
+| 用户 | AI coding 使用者和开发者需要快速判断哪个开源骨架适合自己的新项目。 |
+| 数据 | 初期人工录入骨架项目、分类、标签、评分、推荐理由和文章。 |
+| 现有系统 | 当前仓库为空项目，已建立 harness coding 文档。 |
+| 约束 | 第一版使用 Python 3.12 + Wagtail + SQLite；面向 2 核 2G VPS；不做高并发写入。 |
+
+## 二、用户角色
+
+- **游客 / 未登录用户**：浏览首页、分类页、筛选列表、骨架详情页、文章页。
+- **站点编辑者**：登录 Wagtail 后台，维护骨架项目、场景分类、语言、框架、评分和文章。
+- **站点管理员**：管理后台账号、发布内容、配置导航和 SEO。
+
+第一版不提供前台注册用户。
+
+## 三、功能清单
+
+### 第一版 MVP（最小闭环）
+
+| 功能 | 用户能做什么 | 优先级 |
+| --- | --- | --- |
+| 首页与场景导航 | 用户能从首页看到主场景分类和推荐骨架入口。 | P0 |
+| 骨架项目列表 | 用户能按场景浏览骨架项目列表。 | P0 |
+| 筛选与基础搜索 | 用户能按语言、框架、数据库、AI 友好度筛选。 | P0 |
+| 骨架详情页 | 用户能查看适合场景、技术栈、成熟度、维护状态、功能清单、AI 友好度评分、推荐理由和不适用场景。 | P0 |
+| 后台内容管理 | 编辑者能通过 Wagtail 后台维护项目、分类、标签、评分和文章。 | P0 |
+| SEO 基础 | 公开页面具备 title、description、slug、sitemap 基础能力。 | P0 |
+
+### 后续迭代
+
+| 功能 | 描述 | 阶段 |
+| --- | --- | --- |
+| 付费收录 / 赞助展示 | 保持 Sponsored 标识，和编辑推荐分离。 | V2 |
+| Newsletter | 收集订阅，推送新骨架和评测文章。 | V2 |
+| 用户提交项目 | 用户提交骨架项目，后台审核后发布。 | V2 |
+| Affiliate 链接管理 | 管理云服务、部署平台、AI 工具等返佣链接。 | V2 |
+| 付费数据库 / 会员 | 详细评分、对比表、维护状态提醒。 | V3 |
+| GitHub 数据同步 | 同步 stars、最后提交、issues 等维护指标。 | V3 |
+| PostgreSQL 迁移 | 当写入增加或 SQLite 锁冲突出现时迁移。 | V3 |
+
+## 四、核心用户故事（MVP）
+
+1. 作为游客，我打开首页后能按 SaaS、管理后台、API 服务、内容站、AI 应用等场景进入列表。
+2. 我可以在列表中按语言、框架、数据库、AI 友好度筛选，并看到匹配项目。
+3. 我可以打开骨架详情页，判断它适合什么项目、不适合什么项目、为什么推荐。
+4. 作为编辑者，我可以登录后台新增或修改骨架项目，并发布到前台。
+5. 当某个分类没有项目时，系统展示明确空状态，不报错。
+
+## 五、验收标准（MVP）
+
+- **首页与场景导航**：访问 `/` 时能看到场景入口、推荐项目区和最新文章入口。
+- **骨架项目列表**：访问场景页时能看到该场景下已发布项目；无项目时显示空状态。
+- **筛选与基础搜索**：选择语言或框架筛选后，列表只展示匹配项目；筛选条件可被 URL 表示。
+- **骨架详情页**：详情页展示名称、简介、官网 / GitHub 链接、技术栈、适用场景、不适用场景、AI 友好度评分、维护状态和推荐理由。
+- **后台内容管理**：管理员能在 Wagtail 后台新增项目、分类、语言、框架和评分，并发布后在前台可见。
+- **SEO 基础**：核心公开页面有稳定 slug、页面标题、meta description，并可生成 sitemap。
+
+## 六、范围边界与决策
+
+| 问题 | 决策 |
+| --- | --- |
+| 第一版平台 | Web 网站 |
+| 是否需要账号 | 前台不需要；后台使用 Wagtail 管理员账号 |
+| 第一版范围 | 内容目录 + 筛选 + 详情 + 后台维护 + SEO |
+| 暂不支持 | 用户注册、收藏、评论、支付、自动抓取、复杂搜索、多语言 |
+| 数据库 | 开发和第一版上线使用 SQLite with JSON1 |
+| Python | Python 3.12 |
+
+## 七、待确认 / 风险点
+
+- **数据质量风险**：骨架评分需要人工标准，先在 `04-architecture.md` 固定评分字段。
+- **维护状态风险**：MVP 人工录入维护状态，不自动判断 GitHub 活跃度。
+- **SQLite 并发风险**：多个读通常可接受，多个并发写可能触发锁；出现前台用户提交、评论、会员等写入功能时迁移 PostgreSQL。
+- **SEO 风险**：Wagtail 页面结构和 slug 需要从一开始规范，避免上线后频繁改 URL。
+- **商业信任风险**：赞助展示必须明确标识，不能影响编辑推荐排序。
+- **版权风险**：引用第三方骨架项目时只写摘要、评分和链接，不复制大段 README 或文档内容。
+- **待确认问题**：项目正式名称、域名、视觉风格、首批收录项目清单。

docs/03-tech-stack.md

@@ -0,0 +1,59 @@
+# 技术栈（Tech Stack）
+
+> “用什么”的统一速查表。选型与理由在此集中维护；“怎么把它们搭起来”见 [架构设计](04-architecture.md)。
+
+## 一、技术栈一览
+
+| 维度 | 选型 | 状态 | 理由 / 说明 |
+| --- | --- | --- | --- |
+| CMS / Web 框架 | Wagtail + Django | 已定 | 内容模型、后台、页面、SEO、搜索和后续扩展都适合目录评测站。 |
+| Python | Python 3.12 | 已定 | Wagtail 当前支持 Python 3.12；部署环境更稳。 |
+| 数据库 | SQLite with JSON1 | 已定 | 开发和第一版上线成本低；MVP 写入少。 |
+| 后续数据库 | PostgreSQL | 条件触发 | 出现用户写入、高并发、后台多人编辑、锁冲突或会员功能后迁移。 |
+| 前端模板 | Django Templates / Wagtail Templates | 已定 | 第一版以内容站为主，避免引入前后端分离复杂度。 |
+| UI 样式方案 | 普通 CSS，必要时少量组件化模板 | 已定 | 减少构建链路；后续可再引入 Tailwind。 |
+| 搜索 | Wagtail / 数据库搜索 | 已定 | MVP 不上 Elasticsearch。 |
+| 鉴权方式 | Wagtail Admin Session | 已定 | 第一版只有后台编辑账号。 |
+| 媒体存储 | 本地 media 目录 | 已定 | 2 核 2G VPS 第一版足够；后续可迁移 S3/R2/OSS。 |
+| 部署方式 | 单 VPS，Gunicorn + Nginx | 待实现 | 面向 2 核 2G VPS；先不引入 Docker 作为必需项。 |
+| 测试 | Django test / pytest 待定 | 待定 | T-001 初始化后以项目实际生成结构为准。 |
+
+## 二、决策记录与演进
+
+- 当前选择 **Wagtail**，因为项目核心是内容管理、分类、筛选、详情页和 SEO，不是复杂 SaaS 流程。
+- 当前选择 **SQLite**，因为第一版以公开读为主，后台只有少数编辑者写入。
+- 当前选择 **Python 3.12**，因为比追最新 Python 更稳，且兼容当前 Wagtail。
+- 当前不引入 **前后端分离 React**，避免第一版增加 API、构建和部署复杂度。
+- 当前不引入 **Elasticsearch**，避免在 2 核 2G VPS 上增加运维负担。
+- 当前不引入 **会员/支付系统**，先积累可信内容和 SEO 流量。
+
+## 三、构建与运行命令
+
+生产代码尚未初始化。完成 `T-001` 后必须把本节替换为真实命令。
+
+目标命令形态：
+
+| 用途 | 命令 |
+| --- | --- |
+| 创建虚拟环境 | `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` |
+
+## 四、SQLite 上线纪律
+
+- 上线前验证 SQLite 支持 JSON1。
+- 上线前启用 WAL 模式。
+- 每天备份 `db.sqlite3` 和 `media/`。
+- Gunicorn worker 控制在 1-2 个。
+- 不做高频写入功能。
+- 出现 `database is locked`、用户提交、评论、收藏、会员、多人后台编辑时，优先迁移 PostgreSQL。
+
+## 五、依赖纪律
+
+- 新增第三方依赖前，先说明用途、替代方案和维护成本。
+- 不确定的技术选型先更新本文，再进入代码。
+- 不允许同一职责并存两套框架或两套状态管理方案。
+- 不要为了前端效果提前引入复杂构建链路。

docs/04-architecture.md

@@ -0,0 +1,169 @@
+# 架构设计
+
+> 本文讲“怎么把技术栈搭起来”：系统结构、职责划分、数据模型、技术难点、开发顺序。
+
+## 一、系统结构
+
+```text
+游客 / 搜索引擎 / 后台编辑者
+  |
+  v
+Nginx
+  |
+  v
+Gunicorn
+  |
+  v
+Django + Wagtail
+  |
+  +--> Wagtail Pages / Snippets / Admin
+  +--> Templates / Static / Media
+  |
+  v
+SQLite db.sqlite3
+```
+
+第一版没有独立前端应用，也没有公开业务 API。页面由 Wagtail/Django 渲染。
+
+## 二、职责划分
+
+**Wagtail / Django**
+
+- 管理页面、骨架项目、分类、标签、评分和文章。
+- 提供后台编辑、草稿、发布、slug、SEO 字段。
+- 渲染公开页面。
+- 提供基础搜索和筛选。
+
+**模板层**
+
+- 首页、场景页、语言页、框架页、骨架详情页、文章页。
+- 展示筛选状态、空状态、评分、推荐理由、外部链接。
+- 不承载业务规则和数据修正逻辑。
+
+**数据层**
+
+- SQLite 保存 Wagtail 内容、用户、权限、页面树、项目条目和评分。
+- `media/` 保存上传图片。
+- 不在数据库保存真实密钥、token 或第三方平台凭证。
+
+**部署层**
+
+- Nginx 处理 HTTPS、静态文件、媒体文件和反向代理。
+- Gunicorn 运行 Django。
+- SQLite 文件和 media 目录必须纳入备份。
+
+## 三、数据模型
+
+### 3.1 Wagtail Page 类型
+
+| 模型 | 类型 | 说明 |
+| --- | --- | --- |
+| `HomePage` | Page | 首页，展示场景入口、推荐骨架、最新文章。 |
+| `ScenarioIndexPage` | Page | 场景总览页。 |
+| `ScenarioPage` | Page | 单个场景页，如 SaaS、管理后台、API 服务。 |
+| `SkeletonProjectPage` | Page | 骨架项目详情页。 |
+| `ArticleIndexPage` | Page | 文章列表。 |
+| `ArticlePage` | Page | 评测、对比、避坑指南等内容文章。 |
+
+### 3.2 Snippet / 辅助模型
+
+| 模型 | 说明 |
+| --- | --- |
+| `Language` | Python、TypeScript、Go、Java、PHP 等。 |
+| `Framework` | Wagtail、Django、FastAPI、Next.js、Laravel 等。 |
+| `DatabaseOption` | SQLite、PostgreSQL、MySQL、MongoDB 等。 |
+| `SkeletonFeature` | Auth、Admin、Payment、SEO、Docker、Tests 等功能标签。 |
+| `AiCodingScore` | AI 友好度评分维度定义。 |
+| `SponsorSlot` | 后续赞助展示位置，MVP 可先不启用。 |
+| `AffiliateLink` | 后续返佣链接，MVP 可先不启用。 |
+
+### 3.3 `SkeletonProjectPage` 核心字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `title` | Wagtail Page title | 项目名称。 |
+| `summary` | Text | 一句话简介。 |
+| `github_url` | URL | GitHub 地址。 |
+| `official_url` | URL，可空 | 官网或文档。 |
+| `license_name` | Char | 开源协议。 |
+| `scenario` | relation | 适合场景。 |
+| `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 | 目录结构清晰度。 |
+| `tests_score` | Integer 0-5 | 测试可用性。 |
+| `example_score` | Integer 0-5 | 示例模块完整度。 |
+| `dependency_score` | Integer 0-5 | 依赖克制度。 |
+| `recommended_for` | RichText / StreamField | 适合什么情况。 |
+| `not_recommended_for` | RichText / StreamField | 不适合什么情况。 |
+| `review_notes` | RichText / StreamField | 编辑评测。 |
+| `is_featured` | Boolean | 是否首页推荐。 |
+| `is_sponsored` | Boolean | 是否赞助展示，必须前台标识。 |
+
+### 3.4 URL 与筛选
+
+筛选条件必须可以通过 URL 表达，便于 SEO 和分享：
+
+```text
+/scenarios/saas/
+/scenarios/saas/?language=python
+/projects/?framework=wagtail&database=sqlite
+```
+
+MVP 可以使用服务端查询和分页，不做前端复杂状态管理。
+
+## 四、关键技术难点
+
+| 难点 | 说明 | 应对 |
+| --- | --- | --- |
+| Wagtail 内容模型设计 | Page 和 Snippet 边界如果设计错，后续迁移成本高。 | 先实现最小字段，避免过度抽象；模型变化同步文档。 |
+| SQLite 上线 | 读多写少可行，但并发写有限。 | MVP 不做前台写入；启用 WAL；设置迁移 PostgreSQL 条件。 |
+| 筛选与 SEO | 筛选如果只靠前端状态，不利于搜索引擎和分享。 | 使用服务端查询和可分享 URL。 |
+| 评分可信度 | AI 友好度评分容易主观。 | 固定评分维度，详情页展示评分理由。 |
+| 赞助与推荐冲突 | 商业化会损害信任。 | Sponsored 必须显式标识，和编辑推荐分离。 |
+
+## 五、推荐开发顺序
+
+1. 初始化 Wagtail 项目骨架，确认 Python 3.12 + SQLite 可运行。
+2. 建立基础 Page / Snippet 模型和迁移。
+3. 在后台录入首批示例数据。
+4. 实现首页、场景页、列表页、详情页。
+5. 实现筛选、基础搜索、空状态。
+6. 补 SEO、sitemap、robots、部署说明。
+7. 上线前配置 SQLite WAL、备份策略、Nginx/Gunicorn。
+
+## 六、项目结构建议
+
+T-001 初始化后目标结构：
+
+```text
+skelet/
+├── docs/
+├── manage.py
+├── requirements.txt
+├── skelet/
+│   ├── settings/
+│   ├── urls.py
+│   └── wsgi.py
+├── core/
+│   ├── models.py
+│   ├── templates/
+│   └── static/
+├── tests/
+├── media/
+└── README.md
+```
+
+实际路径以初始化后的 Wagtail 项目为准；初始化完成后必须更新本文和 `current-state.md`。
+
+## 七、架构纪律
+
+- 业务事实和 schema 变化必须同步更新本文。
+- 不在代码里发明文档没有的接口、字段和状态。
+- 不把静态内容、用户数据、缓存数据混在一个模型里。
+- 高风险模块先单独验证，再接入完整页面或流程。

docs/05-coding-rules.md

@@ -0,0 +1,84 @@
+# 编码规则（Coding Rules）
+
+> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。
+
+## 0. 黄金法则
+
+1. **不臆造**：数据字段、文件、接口、依赖，不确定就查证或询问。
+2. **守范围**：只做当前任务要求的事，不顺手加后续功能。
+3. **照架构**：使用 Wagtail / Django / Python 3.12 / SQLite 的既定方案，不擅自换栈。
+4. **小步改**：一次只解决一个任务，不夹带无关重构。
+5. **可验证**：改完必须能构建、能测试、对得上验收标准。
+
+## 1. 动手前
+
+- 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
+- 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
+- 先找现有 Wagtail/Django 结构、模型、模板和测试，复用优先。
+- 如果需求含糊，或改动会偏离原则 / 架构，先问。
+
+## 2. 事实来源纪律
+
+- 只相信文档指定的权威需求、模型、路由、API 边界和当前代码。
+- 不从聊天记录、备份、草稿、旧导出文件里推断当前事实。
+- 不虚构字段、接口、状态码、配置项。
+- 数据结构变化必须同步更新 `04-architecture.md`、`api.md`、`routes.md` 和相关任务。
+
+## 3. 范围纪律
+
+- MVP 只做 `02-requirements.md` 中列为 P0 的功能。
+- V2 / V3 功能只记录，不实现。
+- 需求明确排除的非目标不得实现。
+- 不为“将来可能用到”提前抽象。
+
+## 4. 架构纪律
+
+- 技术栈以 `03-tech-stack.md` 为准。
+- 新增依赖前先说明理由；未经确认不要引入重量级依赖。
+- Page / Snippet / Template / Settings 的职责以 `04-architecture.md` 为准。
+- 公开路由以 `routes.md` 为准。
+- MVP 不提供公开 REST API；不要擅自新增 API 层。
+
+## 5. Wagtail / Django 规则
+
+- 模型字段必须有清晰业务含义，不能只为页面展示临时堆字段。
+- 迁移文件必须随模型变化提交。
+- Wagtail 后台字段分组要服务编辑体验。
+- 前台模板不要写复杂业务查询；复杂查询放到模型方法、QuerySet 或 view/helper。
+- URL slug 要稳定，避免上线后频繁修改。
+- 上传媒体走 Wagtail / Django media 机制，不硬编码本地绝对路径。
+
+## 6. SQLite 规则
+
+- 不写 SQLite 专属 SQL，保持未来迁移 PostgreSQL 的可能性。
+- 不做高频写入功能。
+- 上线前启用 WAL 并记录备份策略。
+- 如果出现 `database is locked`，先记录到 `current-state.md`，再规划 PostgreSQL 迁移任务。
+
+## 7. 测试与验证
+
+生产代码尚未初始化。完成 T-001 后，把真实命令填入这里，并同步 `init.ps1` / `init.sh`：
+
+```powershell
+# 目标形态
+.\.venv\Scripts\python manage.py check
+.\.venv\Scripts\python manage.py test
+```
+
+完成前至少检查：
+
+- [ ] Django system check 通过。
+- [ ] 相关测试通过。
+- [ ] 对得上需求验收标准。
+- [ ] 没有夹带无关改动。
+- [ ] 涉及文档事实变化时，文档已同步。
+- [ ] 已在 `../progress.md` 记录跑过的命令和结果作为证据。
+- [ ] 回复里如实说明跑了什么命令、结果如何。
+
+## 8. 绝不
+
+- 绝不把密钥、token、密码写进代码或文档样例的真实值里。
+- 绝不为了让测试通过而删除断言、降低验收标准。
+- 绝不擅自删除用户已有文件或重置工作区。
+- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。
+- 绝不把赞助项目伪装成编辑推荐。

docs/06-tasks.md

@@ -0,0 +1,66 @@
+# 任务看板（Tasks）
+
+> 把 MVP 拆成小步、可独立交付的任务，让 AI 一步一步开发，避免一次生成整个项目。
+
+## 使用规则
+
+1. 每轮只领取一个状态为 `TODO`、且依赖均已 `DONE` 的任务，取最靠前的那个。
+2. 开始前把任务改成 `DOING`。
+3. 完成后跑验证，把证据追加到 [`../progress.md`](../progress.md)，再改成 `DONE`。
+4. 同步更新 [`current-state.md`](current-state.md)。
+5. 不实现 Backlog 或后续阶段功能，除非任务已明确要求。
+
+## 状态图例
+
+`TODO` 待开始 · `DOING` 进行中 · `DONE` 已完成并验收 · `BLOCKED` 受阻
+
+---
+
+## Phase 0 · 地基
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-000 | 初始化 harness 文档 | - | 根目录入口、需求、技术栈、架构、规则、任务和当前状态文档已建立 | DONE |
+| T-001 | 初始化 Wagtail 项目骨架 | T-000 | Python 3.12 虚拟环境可用；Wagtail/Django 项目生成；SQLite 配置可 migrate；首页或默认 Wagtail 页面可访问；`init.ps1` / `init.sh` 替换为真实命令 | TODO |
+| T-002 | 建立基础配置与环境样例 | T-001 | 存在 `requirements.txt`、`.env.example` 或等价配置说明；不包含真实密钥；`DEBUG`、`ALLOWED_HOSTS`、media/static 配置清楚 | TODO |
+| T-003 | 建立最小验证基线 | T-001 | `manage.py check` 和基础测试命令可运行；验证结果写入 `progress.md` | TODO |
+
+## Phase 1 · 内容模型
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-101 | 建立场景、语言、框架、数据库、功能标签模型 | T-003 | Wagtail 后台可维护这些 Snippet；迁移文件生成并通过 migrate | TODO |
+| T-102 | 建立骨架项目详情模型 | T-101 | `SkeletonProjectPage` 包含架构文档中的 MVP 字段；后台编辑分组清晰；字段校验合理 | TODO |
+| T-103 | 建立文章模型 | T-101 | 可维护文章列表和详情；文章可链接骨架项目 | TODO |
+| T-104 | 准备首批种子内容 | T-102, T-103 | 至少有 3 个场景、5 个骨架项目、2 篇文章；数据来源和人工录入方式记录清楚 | TODO |
+
+## Phase 2 · 前台 MVP
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-201 | 实现基础页面框架 | T-104 | `base.html`、导航、页脚、基础样式可用；移动端不溢出 | TODO |
+| T-202 | 实现首页 | T-201 | 首页展示场景入口、推荐骨架和最新文章 | TODO |
+| T-203 | 实现场景页和项目列表页 | T-202 | 场景页展示对应项目；项目列表支持分页和空状态 | TODO |
+| T-204 | 实现筛选与基础搜索 | T-203 | URL 参数可筛选语言、框架、数据库、AI 分数和关键词 | TODO |
+| T-205 | 实现骨架详情页 | T-204 | 展示需求文档要求的详情字段、评分、推荐理由和 Sponsored 标识 | TODO |
+| T-206 | 实现文章列表和文章详情 | T-203 | 文章可访问，可链接项目详情 | TODO |
+
+## Phase 3 · SEO 与上线准备
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| 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 |
+
+## Backlog
+
+- 用户提交骨架项目并后台审核。
+- Newsletter 订阅。
+- Affiliate 链接管理。
+- 赞助位管理与展示。
+- 付费数据库 / 会员。
+- GitHub 维护状态自动同步。
+- PostgreSQL 迁移。
+- 多语言站点。

docs/README.md

@@ -0,0 +1,41 @@
+# 项目文档导航
+
+## 一句话定位
+
+Skelet 是一个面向 AI coding 开发者、独立开发者和小团队的开源项目骨架导航与评测网站，用于解决“从哪个稳定骨架开始新项目更省 token、更省时间、更不容易跑偏”的决策问题，第一版先完成“浏览分类 -> 筛选骨架 -> 查看详情与评分 -> 形成选型判断”的 MVP 闭环。
+
+## 文档导航
+
+- [`../AGENTS.md`](../AGENTS.md)：Codex / 通用 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 每次开始工作的入口、阅读顺序和任务领取规则。
+- [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。
+- [需求](02-requirements.md)：MVP 要什么、怎么算达成。
+- [技术栈](03-tech-stack.md)：Wagtail / Django / Python / SQLite 等技术选型和运行命令。
+- [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。
+- [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。
+- [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个。
+- [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)：标准启动与验证入口脚本；生产代码初始化后再替换真实命令。
+
+## 任务 / 进度 / 当前状态
+
+- `06-tasks.md` 维护任务看板：任务 ID、依赖、验收要点和状态。
+- `../progress.md` 维护执行进度：每轮实际做了什么、跑了什么验证、遇到什么阻塞、做了什么决策。
+- `current-state.md` 维护当前快照：当前目录、当前可运行命令、已完成任务摘要和下一个可领取任务。
+
+## 维护原则
+
+- 需求变化先改 `02-requirements.md`，再改代码。
+- 技术方案变化先改 `03-tech-stack.md` 和 `04-architecture.md`，再改代码。
+- 代码现实变化后同步 `current-state.md` 和 `06-tasks.md`，执行过程追加到 `../progress.md`。
+- MVP 范围外的商业化、会员、用户投稿、复杂搜索只进入 Backlog，不提前实现。

docs/adoption-checklist.md

@@ -0,0 +1,46 @@
+# 已有项目接入 / 恢复清单
+
+> 本项目当前是空目录起步，已完成 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/api.md

@@ -0,0 +1,78 @@
+# API / 模块合约
+
+> MVP 是服务端渲染内容站，不提供公开业务 API。本文记录 Wagtail/Django 边界和后续 API 扩展原则。
+
+## 通用约定
+
+- 前台页面：Django / Wagtail 服务端渲染 HTML。
+- 后台管理：Wagtail Admin Session。
+- MVP 公开 API：无。
+- 时间格式：后台和数据库使用 Django 默认时区配置；前台展示按站点配置格式化。
+- 未登录访问后台：由 Wagtail Admin 重定向到登录页。
+
+## MVP 页面输入合约
+
+MVP 的“接口”主要是 URL 参数。
+
+### `GET /projects/`
+
+查询参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `scenario` | 场景 slug，可选。 |
+| `language` | 语言 slug，可选。 |
+| `framework` | 框架 slug，可选。 |
+| `database` | 数据库 slug，可选。 |
+| `min_ai_score` | AI 友好度最低分，可选。 |
+| `q` | 基础搜索关键词，可选。 |
+
+响应：HTML 页面，展示匹配项目列表、当前筛选条件和空状态。
+
+### `GET /projects/{slug}/`
+
+响应：HTML 页面，展示骨架项目详情。
+
+必须包含：
+
+- 项目名称和简介。
+- GitHub / 官网链接。
+- 技术栈。
+- 适合场景和不适合场景。
+- AI 友好度评分和评分理由。
+- 维护状态。
+- 推荐理由。
+- Sponsored 标识，如适用。
+
+## 后台内容边界
+
+后台使用 Wagtail Admin，不单独开发自定义管理 API。
+
+管理员可维护：
+
+- `SkeletonProjectPage`
+- `ScenarioPage`
+- `ArticlePage`
+- `Language`
+- `Framework`
+- `DatabaseOption`
+- `SkeletonFeature`
+
+## 后续 API 原则
+
+只有出现以下需求时才新增 API：
+
+- 前台异步筛选必须无刷新更新。
+- 用户提交骨架项目。
+- 外部系统读取项目数据库。
+- GitHub 数据同步任务需要内部端点。
+
+新增 API 前必须先更新本文，至少写清路径、鉴权方式、请求字段、响应字段、错误码、幂等性和频率限制。
+
+## 错误与降级
+
+- 筛选无结果：展示空状态，不返回 500。
+- slug 不存在：返回 404 页面。
+- 外部链接为空：不展示链接按钮。
+- Sponsored 项目：必须展示赞助标识。
+- 后台未登录：使用 Wagtail 默认登录流程。

docs/clean-state-checklist.md

@@ -0,0 +1,16 @@
+# 干净收尾检查清单
+
+> 每轮会话结束前逐项过一遍，确保仓库处于"下一轮无需人工修复即可直接开工"的状态。
+> 这是把"提前宣告完成"挡在门外的最后一道关卡，配合 [`05-coding-rules.md`](05-coding-rules.md) 的验证清单使用。
+
+收尾前确认：
+
+- [ ] 标准启动路径仍可用（`./init.sh` 或本项目等价命令能跑通）。
+- [ ] 标准验证 / smoke 仍可运行，结果如实。
+- [ ] 本轮执行记录已追加到 [`../progress.md`](../progress.md)（含跑过的命令和结果作为证据）。
+- [ ] [`06-tasks.md`](06-tasks.md) 任务状态真实反映 `DONE` 与未验证的边界，没有"假 DONE"。
+- [ ] [`current-state.md`](current-state.md) 已覆盖更新到当前快照（目录、命令、下一步、blocker）。
+- [ ] 没有半成品改动处于未记录状态；如有，已写明 `BLOCKED` / `PARTIAL` 和原因。
+- [ ] 代码处于可安全恢复的状态（必要时已提交，提交信息清晰）。
+
+任意一项不满足，就先补到满足，再结束会话。

docs/current-state.md

@@ -0,0 +1,71 @@
+# 当前实现状态
+
+> 本文是可覆盖的当前快照，记录代码与任务看板的现实状态，帮助 AI coding agent 避免只看计划而忽略仓库现状。
+
+## 职责边界
+
+- [`06-tasks.md`](06-tasks.md)：任务看板，维护任务状态、依赖和验收要点。
+- [`../progress.md`](../progress.md)：执行流水，只追加记录每轮执行、验证、阻塞和决策。
+- `current-state.md`：当前快照，可覆盖更新当前目录、当前命令、已完成摘要和下一步。
+
+## 当前快照
+
+- 日期：2026-07-06
+- 阶段：MVP 起步前，harness 文档已初始化
+- 技术栈：目标为 Wagtail + Django + Python 3.12 + SQLite
+- 生产代码：尚未初始化
+- 测试：尚未初始化
+- 数据：尚未建立 seed 数据；未来通过 Wagtail 后台录入首批项目
+- 标准启动路径：`init.ps1` / `init.sh` 尚未配置真实命令
+- 标准验证路径：生产代码初始化后补齐
+- 当前 blocker：未初始化 Wagtail 项目骨架；下一步执行 `T-001`
+
+## 当前目录要点
+
+| 路径 | 状态 | 说明 |
+| --- | --- | --- |
+| `docs/` | 已有 | harness coding 文档和项目需求 / 方案。 |
+| `AGENTS.md` | 已有 | AI agent 仓库入口。 |
+| `CLAUDE.md` | 已有 | Claude Code 薄入口。 |
+| `progress.md` | 已有 | 只追加执行流水。 |
+| `init.ps1` / `init.sh` | 已有，占位 | T-001 初始化生产代码后替换真实命令。 |
+| `manage.py` | 待建 | Wagtail/Django 入口。 |
+| `requirements.txt` | 待建 | Python 依赖。 |
+| `skelet/` | 待建 | Django 项目配置。 |
+| `core/` | 待建 | Wagtail 页面模型、模板和静态资源。 |
+| `tests/` | 待建 | 测试目录。 |
+
+## 任务看板状态
+
+- 已完成：`T-000 初始化 harness 文档`。
+- 正在进行：无。
+- 下一个可领取任务：`T-001 初始化 Wagtail 项目骨架`。
+
+## 当前可运行内容
+
+```powershell
+# 当前只能做文档检查
+Get-ChildItem -Recurse -File
+```
+
+生产应用命令待 T-001 初始化后补齐：
+
+```powershell
+# 目标形态
+.\.venv\Scripts\python manage.py check
+.\.venv\Scripts\python manage.py test
+.\.venv\Scripts\python manage.py runserver
+```
+
+## 开始编码前检查
+
+1. 读仓库级 agent 规则文件。
+2. 读 `docs/00-ai-start-here.md`。
+3. 读 `docs/05-coding-rules.md`。
+4. 在 `docs/06-tasks.md` 取第一个 `TODO` 且依赖均 `DONE` 的任务。
+5. 将该任务状态改为 `DOING`。
+
+## 维护规则
+
+当实际代码状态发生变化时，同步更新本文件、`docs/06-tasks.md` 和 `progress.md`。
+

docs/evaluator-rubric.md

@@ -0,0 +1,43 @@
+# 评审评分表
+
+> 在一轮（或几轮）会话实现完成后、正式验收前，用这张表做一次结构化评审，回答"这轮 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

@@ -0,0 +1,31 @@
+# 方法对照表
+
+> 把最常见的长时 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

@@ -0,0 +1,45 @@
+# 质量文档
+
+> 跟踪代码库随时间是变强还是变弱。它评的是代码库本身的质量；单次 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 入口和任务看板的问题已关闭。

docs/routes.md

@@ -0,0 +1,79 @@
+# 路由与页面结构
+
+> 本文约定前台页面路由、页面职责和组件归属。
+
+## 页面路由
+
+| 路由 | 页面 | MVP 说明 |
+| --- | --- | --- |
+| `/` | 首页 | 展示场景入口、推荐骨架、最新文章。 |
+| `/scenarios/` | 场景总览页 | 展示所有场景分类。 |
+| `/scenarios/{slug}/` | 场景详情 / 列表页 | 展示某个场景下的骨架项目。 |
+| `/projects/` | 骨架项目列表页 | 支持语言、框架、数据库、AI 分数和关键词筛选。 |
+| `/projects/{slug}/` | 骨架详情页 | 展示项目详情、评分、推荐理由和外部链接。 |
+| `/languages/{slug}/` | 语言聚合页 | MVP 可由筛选页替代。 |
+| `/frameworks/{slug}/` | 框架聚合页 | MVP 可由筛选页替代。 |
+| `/articles/` | 文章列表页 | 展示评测、对比、避坑指南。 |
+| `/articles/{slug}/` | 文章详情页 | 展示文章正文。 |
+| `/admin/` | Wagtail Admin | 后台内容维护。 |
+
+## 页面职责
+
+### 首页
+
+- 展示主场景分类。
+- 展示推荐骨架项目。
+- 展示最新文章。
+- 引导进入项目列表和场景页。
+
+### 场景页
+
+- 展示该场景说明。
+- 展示该场景下骨架项目。
+- 支持跳转项目详情。
+- 无项目时展示空状态。
+
+### 项目列表页
+
+- 展示所有已发布骨架项目。
+- 支持按语言、框架、数据库、AI 分数、关键词筛选。
+- 筛选条件体现在 URL 查询参数中。
+- 展示当前筛选条件和清除筛选入口。
+
+### 项目详情页
+
+- 根据 slug 定位单个骨架项目。
+- 展示核心信息、技术栈、评分、适用场景、不适用场景、推荐理由。
+- 外部链接打开到 GitHub / 官网。
+- 如果是赞助项目，展示 Sponsored 标识。
+
+### 文章页
+
+- 展示评测、对比、避坑指南。
+- 文章可以链接到骨架详情页。
+
+### 后台
+
+- 使用 Wagtail Admin。
+- 编辑者维护项目、分类、标签、评分和文章。
+- 不开发单独后台前端。
+
+## 模板 / 组件建议
+
+| 模板 / 组件 | 归属 | 说明 |
+| --- | --- | --- |
+| `base.html` | 全局 | 页面框架、导航、SEO block、页脚。 |
+| `home_page.html` | 首页 | 场景入口、推荐项目、最新文章。 |
+| `project_card.html` | 通用 include | 项目卡片。 |
+| `project_filters.html` | 列表页 include | 筛选控件。 |
+| `score_badge.html` | 通用 include | AI 友好度评分展示。 |
+| `sponsored_badge.html` | 通用 include | 赞助标识。 |
+| `empty_state.html` | 通用 include | 无结果状态。 |
+
+## 导航规则
+
+- 首页进入场景页：点击场景入口。
+- 场景页进入项目详情：点击项目卡片。
+- 项目列表保留筛选条件，清除筛选后回到 `/projects/`。
+- 后台只通过 `/admin/` 访问。
+- 权限不足使用 Wagtail 默认后台权限处理。