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
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 入口和任务看板的问题已关闭。