Harden task board and specs for weaker coding agents

- 06-tasks: add per-task detail sheets for Phase 0/1 (concrete init
  commands, BLOCKED preconditions, verification commands with expected
  results) and a constraint/verification quick table for Phase 2/3;
  replace subjective acceptance wording with checkable items
- 04-architecture: promote 3.4 to an authoritative filter-param
  contract (names, values, AND combination, invalid-value handling);
  add required/optional/default field annex with 0-5 validators to
  3.3; state AiCodingScore is not a model in MVP; record structure
  decision (keep wagtail-start home/search apps, business models in
  new core app, no Dockerfile)
- 03-tech-stack: add version-pinning policy row for T-001
- routes/02-requirements: point filter wording back to the 3.4
  contract instead of maintaining copies
- T-104: human-input boundary - seed projects, scores and verdicts
  must be user-confirmed; BLOCKED without a confirmed list
- current-state snapshot updated; maintenance record appended to
  progress.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
ila
2026-07-06 16:11:54 +08:00
co-authored by Claude Fable 5
parent d98bfb7531
commit 678d081124
7 changed files with 147 additions and 21 deletions
+43 -11
View File
@@ -65,6 +65,8 @@ SQLite db.sqlite3
| `ArticleIndexPage` | Page | 文章列表。 |
| `ArticlePage` | Page | 评测、对比、避坑指南等内容文章。 |
模型归属:`HomePage` 在 `home` app(`wagtail start` 生成,沿用不改名);其余 Page、Snippet 和文章模型集中在 `core` app(见本文第六节)。
### 3.2 Snippet / 辅助模型
| 模型 | 说明 |
@@ -73,7 +75,7 @@ SQLite db.sqlite3
| `Framework` | Wagtail、Django、FastAPI、Next.js、Laravel 等。 |
| `DatabaseOption` | SQLite、PostgreSQL、MySQL、MongoDB 等。 |
| `SkeletonFeature` | Auth、Admin、Payment、SEO、Docker、Tests 等功能标签。 |
| `AiCodingScore` | AI 友好度评分维度定义。 |
| `AiCodingScore` | **MVP 不建此模型**:评分维度即 `SkeletonProjectPage` 的 6 个分数字段(见 3.3),避免两处维护同一套维度。 |
| `SponsorSlot` | 后续赞助展示位置,MVP 可先不启用。 |
| `AffiliateLink` | 后续返佣链接,MVP 可先不启用。 |
@@ -105,6 +107,13 @@ SQLite db.sqlite3
| `is_featured` | Boolean | 是否首页推荐。 |
| `is_sponsored` | Boolean | 是否赞助展示,必须前台标识。 |
**必填 / 可空 / 默认(后台校验以此为准,实现不得自行猜测)**:
- 必填:`title`、`summary`、`github_url`、`scenarios`(至少 1 个)、`languages`(至少 1 个)、`maturity`、6 个评分字段、`recommended_for`。
- 可空:`official_url`、`license_name`、`frameworks`、`databases`、`features`、`not_recommended_for`、`review_notes`。
- 默认:`maintenance_status='unknown'`、`is_featured=False`、`is_sponsored=False`。
- 6 个评分字段使用 `MinValueValidator(0)` / `MaxValueValidator(5)`。
**评分模型纪律(唯一权威定义)**:
- AI Coding 友好度评分维度以上表 6 个 0-5 分项为唯一权威:目录结构、文档完整度、测试可用性、示例模块、依赖克制度、增量开发难度。
@@ -112,17 +121,36 @@ SQLite db.sqlite3
- `business/` 下的文档引用本节,不得自行维护另一份维度清单。
- 每个项目除分数外必须有一句评语:为什么适合 / 不适合 AI coding。
### 3.4 URL 与筛选
### 3.4 URL 与筛选参数契约(唯一权威)
筛选条件必须可以通过 URL 表达,便于 SEO 和分享:
筛选条件必须可以通过 URL 表达,便于 SEO 和分享。列表页查询参数按下表实现,视图、模板和其他文档不得另造参数名或语义:
| 参数 | 取值 | 语义 |
| --- | --- | --- |
| `language` | `Language.slug`,单值 | 项目 `languages` 包含该语言 |
| `framework` | `Framework.slug`,单值 | 项目 `frameworks` 包含该框架 |
| `database` | `DatabaseOption.slug`,单值 | 项目 `databases` 包含该数据库 |
| `min_score` | 0-30 整数 | `total_score`(6 分项之和)≥ 该值 |
| `q` | 关键词字符串 | `title` 或 `summary` 不区分大小写包含(ORM `icontains`,MVP 不接搜索后端) |
| `page` | ≥1 整数 | 分页页码,每页 20 条 |
组合规则:
- 参数均可选,多个参数同时出现时按 AND 组合。
- MVP 每个参数只取单值;同名参数重复出现时取第一个。
- `min_score` / `page` 无法解析为合法整数时忽略该参数,不报错。
- 未知 slug 正常参与过滤,自然得到空列表并渲染空状态。
示例:
```text
/scenarios/saas/
/scenarios/saas/?language=python
/projects/?framework=wagtail&database=sqlite
/projects/?framework=wagtail&database=sqlite&min_score=18
/projects/?q=admin&page=2
```
MVP 可以使用服务端查询和分页,不做前端复杂状态管理。
MVP 使用服务端查询和分页,不做前端复杂状态管理。
## 四、关键技术难点
@@ -146,26 +174,30 @@ MVP 可以使用服务端查询和分页,不做前端复杂状态管理。
## 六、项目结构建议
T-001 初始化后目标结构:
T-001 初始化后目标结构(与 `wagtail start skelet .` 的实际输出对齐):
```text
skelet/
├── docs/
├── manage.py
├── requirements.txt
├── skelet/
│ ├── settings/
├── skelet/ # wagtail start 生成的配置包
│ ├── settings/ # base.py / dev.py / production.py
│ ├── urls.py
│ └── wsgi.py
├── core/
├── home/ # wagtail start 生成,保留,承载 HomePage
├── search/ # wagtail start 生成,保留
├── core/ # 新建业务 app:Snippet、场景页、项目页、文章模型
│ ├── models.py
│ ├── templates/
│ └── static/
├── tests/
│ ├── static/
│ └── tests.py
├── media/
└── README.md
```
**结构决策**:保留 `wagtail start` 生成的 `home` 和 `search` app,不重命名(手改默认迁移容易出错);业务模型全部放在新建的 `core` app;测试放各 app 的 `tests.py`,暂不建独立 `tests/` 目录;生成的 `Dockerfile` 删除(第一版不用 Docker,见 `03-tech-stack.md`)。
实际路径以初始化后的 Wagtail 项目为准;初始化完成后必须更新本文和 `current-state.md`。
## 七、架构纪律