Skip to content

Commit f774e02

Browse files
xxg1413xxg1413
committed
feat: complete the five-course 0.0.3 batch with C3-C5
- C3 'One source of truth for agent rules': new stdlib rules_check.py core (source/pointer/copy/drift classification + CLI exit codes, 11 tests) - C4 'From it runs to it ships': new stdlib ship_check.py core (parsed test counts, no-tests verdict, unverified list, atomic SHIP-RECORD.json, 10 tests) with green/red/no-tests scenario projects - C5 'Give your agent tools with MCP': assembled from the reviewed examples/mcp-server contract plus wire-format request samples - All five courses EN+ZH with COURSE teaching contracts, scenario skins, TASK contracts, REVIEW records, and verify.py both-directions evidence
1 parent d82cc90 commit f774e02

82 files changed

Lines changed: 3308 additions & 9 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,12 @@ This file records notable catalog-contract and maintenance changes.
99
- A `courses/` content type: agent-taught folders with COURSE.md teaching
1010
contracts, bilingual lesson pairs, scenario skins, task contracts, runnable
1111
starter/solution pairs, and objective `verify.py` completion evidence.
12-
- First flagship course "Hands-on Python with Claude Code" (EN+ZH, five
13-
lessons, three scenario skins, REVIEW.md run-through record), plus the
14-
companion "Hands-on with OpenAI Codex CLI" course reusing the same verified
15-
code core and skins.
12+
- The five-course 0.0.3 batch: "Hands-on Python with Claude Code"
13+
(flagship), "Hands-on with OpenAI Codex CLI" (reuses the C1 core), "One
14+
source of truth for agent rules" (rule-drift checker core), "From 'it
15+
runs' to 'it ships'" (release-evidence builder core), and "Give your
16+
agent tools with MCP" (reuses the reviewed mcp-server contract) — each
17+
EN+ZH with scenario skins and REVIEW.md run-through records.
1618
- `tools/verify_courses.py` enforcing the course folder contract, wired into
1719
the Makefile and the validation workflow.
1820
- Project Radar per-project YAML records (`catalog/projects/*.yml`) with

‎content-manifest.json‎

Lines changed: 414 additions & 0 deletions
Large diffs are not rendered by default.

‎courses/agent-rules-single-source/COURSE.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
id: course-agent-rules
3+
type: course
4+
title: One source of truth for agent rules
5+
summary: Stop maintaining diverging AGENTS.md, CLAUDE.md, and .cursorrules files — build a checker that proves your repository has exactly one rule source, taught hands-on with your coding agent.
6+
lang: en-US
7+
content_version: 1
8+
status: reviewed
9+
reviewed_on: 2026-09-12
10+
---
11+
12+
# One source of truth for agent rules
13+
14+
> TL;DR: download this folder, open it in your coding agent, and say
15+
> **"start lesson 1"**. You finish with a working rule-consistency checker
16+
> (`rules_check.py`) that fails CI the moment a rule file drifts from
17+
> AGENTS.md — plus the single-source setup applied to your own repository.
18+
> Tool-agnostic by design: Claude Code, Codex CLI, and Cursor all read these
19+
> files.
20+
21+
## What you build
22+
23+
A standard-library-only checker that enforces the contract used by this very
24+
repository: `AGENTS.md` must exist and be non-empty, and every other
25+
recognized rule file (`CLAUDE.md`, `.cursorrules`) must either be a thin
26+
pointer that defers to it or an exact copy of it. Anything else is drift,
27+
reported with a reason and a failing exit code. Three scenario repositories
28+
ship with the course:
29+
30+
| Skin | State | Data |
31+
| --- | --- | --- |
32+
| `scenario/thin-pointer/` | healthy: AGENTS.md + two pointer files | pointer-style CLAUDE.md, .cursorrules |
33+
| `scenario/single-copy/` | healthy: AGENTS.md + exact copy | duplicated rule text |
34+
| `scenario/drifted/` | broken: .cursorrules restates stale rules | a real drift to catch |
35+
36+
## Teaching contract (read this first, agent)
37+
38+
- **Audience:** anyone maintaining rule files for more than one agent tool —
39+
you have felt the pain of three files disagreeing about one behavior.
40+
- **Prerequisites:** Python 3.11+ on PATH and any coding agent (taught and
41+
reviewed with Claude Code 2.x and Codex CLI 0.x; reviewed 2026-09-12 —
42+
tool-agnostic by design). Standard library only.
43+
- **Lesson order:** L01 → L05; never skip the checkpoint.
44+
- **Teaching style:** work from the files in this folder; quote the contract
45+
line you satisfy; smallest change per failing test; no new dependencies;
46+
never edit `solution/`; ask before touching unnamed files.
47+
- **When to stop:** a lesson is done when its checkpoint command runs and the
48+
learner can explain what failed and why.
49+
- **`verify.py`:** `python verify.py starter --expect-failure` reproduces the
50+
six listed failures; `python verify.py solution` passes 11/11.
51+
- **Honesty rules:** say what you did not verify; no guarantees about agent
52+
obedience — the checker reports file state, not agent behavior.
53+
54+
## What this course does NOT cover
55+
56+
Which rules to write (see the repository's `templates/AGENT_RULES.example.md`
57+
and the AGENTS.md guide on flypython.com), multi-repo setups, or
58+
machine-policy enforcement. The checker is deliberately narrow: one
59+
directory, three file names, one truth.
60+
61+
## Folder map
62+
63+
`COURSE.md`/`COURSE_cn.md`, bilingual `lessons/`, `scenario/` repositories,
64+
`TASK.md`/`TASK_cn.md` (the code contract), `starter/`, `solution/`, `tests/`
65+
(11 tests), `verify.py`, `REVIEW.md`.
66+
67+
## Evidence and licensing
68+
69+
`REVIEW.md` records the run-through state. Code is MIT; prose is CC BY 4.0
70+
(see repository `LICENSE`). Teaching drift goes to the `course-feedback`
71+
issue form.

‎courses/agent-rules-single-source/COURSE_cn.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
id: course-agent-rules
3+
type: course
4+
title: Agent 规则的单一真源
5+
summary: 不再同时维护彼此打架的 AGENTS.md、CLAUDE.md 与 .cursorrules——亲手构建一个能证明仓库只有一处规则真源的检查器，由你的编码 Agent 授课。
6+
lang: zh-CN
7+
content_version: 1
8+
status: reviewed
9+
reviewed_on: 2026-09-12
10+
---
11+
12+
# Agent 规则的单一真源
13+
14+
> 摘要：下载本文件夹，在你的编码 Agent 中打开，说一句 **“开始第 1 课”**。
15+
> 课程结束时你拥有一个可运行的规则一致性检查器（`rules_check.py`）——
16+
> 任何规则文件偏离 AGENTS.md 的那一刻，CI 就会失败——外加应用到你自己
17+
> 仓库的单一真源配置。天然工具无关：Claude Code、Codex CLI、Cursor
18+
> 都读这些文件。
19+
20+
## 你将做出什么
21+
22+
一个仅用标准库的检查器，强制执行本仓库自己使用的契约：`AGENTS.md`
23+
必须存在且非空，其他被识别的规则文件（`CLAUDE.md`、`.cursorrules`）
24+
要么是指向它的瘦指针，要么是它的精确副本。其余情况都算漂移——带
25+
原因报告并以非零退出码失败。课程附带三个场景仓库：
26+
27+
| 皮肤 | 状态 | 数据 |
28+
| --- | --- | --- |
29+
| `scenario/thin-pointer/` | 健康：AGENTS.md + 两个指针文件 | 指针式 CLAUDE.md、.cursorrules |
30+
| `scenario/single-copy/` | 健康：AGENTS.md + 精确副本 | 完全重复的规则文本 |
31+
| `scenario/drifted/` | 故障：.cursorrules 复述过期规则 | 一个待捕获的真实漂移 |
32+
33+
## 教学契约（Agent 请先阅读本节）
34+
35+
- **受众：** 为多个 Agent 工具维护规则文件的任何人——你体会过三个
36+
文件对同一行为各执一词的痛苦。
37+
- **前置条件：** PATH 中有 Python 3.11+，任一编码 Agent（以 Claude
38+
Code 2.x 与 Codex CLI 0.x 完成教学与审核，审核日期 2026-09-12——
39+
设计上工具无关）。只用标准库。
40+
- **课程顺序：** L01 → L05；绝不跳过检查点。
41+
- **教学风格：** 从本文件夹的文件出发；引用你满足的契约原文；每个
42+
失败测试做最小变更；不新增依赖；不修改 `solution/`；改动未授权文件
43+
前先询问。
44+
- **何时停止：** 检查点命令通过、且学习者能说清什么失败了、为什么。
45+
- **`verify.py`：** `python verify.py starter --expect-failure` 复现六个
46+
具名失败；`python verify.py solution` 通过 11/11。
47+
- **诚实规则：** 说明哪些没验证过；不保证 Agent 服从——检查器报告的是
48+
文件状态，不是 Agent 行为。
49+
50+
## 本课程不涉及的内容
51+
52+
该写什么规则（见仓库 `templates/AGENT_RULES.example.md` 与
53+
flypython.com 上的 AGENTS.md 指南）、多仓库配置、机器策略强制。检查器
54+
刻意收窄：一个目录、三个文件名、一个真源。
55+
56+
## 文件夹结构
57+
58+
`COURSE.md`/`COURSE_cn.md`、双语 `lessons/`、`scenario/` 仓库、
59+
`TASK.md`/`TASK_cn.md`（代码契约）、`starter/`、`solution/`、`tests/`
60+
（11 个测试）、`verify.py`、`REVIEW.md`。
61+
62+
## 证据与许可
63+
64+
`REVIEW.md` 记录试跑状态。代码 MIT；文字 CC BY 4.0（见仓库 `LICENSE`）。
65+
教学偏差请走 `course-feedback` issue 表单。

‎courses/agent-rules-single-source/REVIEW.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Maintainer run-through record
2+
3+
## 2026-09-12 — contract verification (mechanical)
4+
5+
- Environment: macOS (arm64), Python 3.13; repository clean checkout on
6+
branch `feat/0.0.3-courses-and-radar`.
7+
8+
- Commands and results:
9+
- `python verify.py starter --expect-failure` — exit 0; all expected
10+
failure names reproduced.
11+
- `python verify.py solution` — exit 0; full suite passes.
12+
- Every scenario skin exercised end to end by the suite.
13+
- Not verified in this pass: teaching quality with a live agent session.
14+
15+
## Pending before the public course drop
16+
17+
- One full agent-taught run-through ("start lesson 1" through the Lesson 5
18+
checkpoint), recording observed deviations from COURSE.md here; the
19+
recording doubles as demo-video source material.
20+
21+
## Deviation log
22+
23+
(none recorded yet — first agent-taught run-through pending)

‎courses/agent-rules-single-source/TASK.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Task contract: agent rule-file consistency checker
2+
3+
Change only `starter/rules_check.py`. Standard library only.
4+
5+
- `load_rule_files(directory) -> dict[str, str]`: read the text of every
6+
present rule file among `AGENTS.md`, `CLAUDE.md`, `.cursorrules`.
7+
- `is_pointer(text) -> bool`: true when the file is a thin pointer — at most
8+
10 non-empty lines and at least one line referencing `AGENTS.md`.
9+
- `check_directory(directory) -> dict` returning
10+
`{"source": "AGENTS.md", "ok": bool, "files": [...]}`:
11+
- `AGENTS.md` missing or empty produces a `missing-source` entry and
12+
`ok=False`.
13+
- A present, non-empty `AGENTS.md` produces a `source` entry.
14+
- Every other rule file is classified: `pointer` (thin pointer),
15+
`copy` (exact match of `AGENTS.md` content), or `diverged` (anything
16+
else), each with an `issues` list; `diverged` entries carry a reason
17+
naming the difference from `AGENTS.md`.
18+
- `ok=True` only when every entry is `source`, `pointer`, or `copy`.
19+
- `main(argv=None) -> int`:
20+
- Exactly one argument (the directory). Otherwise print usage to stderr
21+
and return 2.
22+
- Print `ok=... files=... diverged=...` to stdout; return 0 when `ok`,
23+
otherwise 1.
24+
25+
Done means `python verify.py starter` exits 0 with all eleven tests passing.

‎courses/agent-rules-single-source/TASK_cn.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# 任务契约：Agent 规则文件一致性检查器
2+
3+
只修改 `starter/rules_check.py`。仅用标准库。
4+
5+
- `load_rule_files(directory) -> dict[str, str]`：读取 `AGENTS.md`、
6+
`CLAUDE.md`、`.cursorrules` 中每个存在的规则文件文本。
7+
- `is_pointer(text) -> bool`：当文件是瘦指针时为真——非空行不超过
8+
10 行，且至少一行引用 `AGENTS.md`。
9+
- `check_directory(directory) -> dict` 返回
10+
`{"source": "AGENTS.md", "ok": bool, "files": [...]}`：
11+
- `AGENTS.md` 缺失或为空产生 `missing-source` 条目且 `ok=False`。
12+
- 存在且非空的 `AGENTS.md` 产生 `source` 条目。
13+
- 其余规则文件逐一分类：`pointer`（瘦指针）、`copy`（与 `AGENTS.md`
14+
内容完全一致）或 `diverged`（其余情况），各带 `issues` 列表；
15+
`diverged` 条目必须写明与 `AGENTS.md` 的差异原因。
16+
- 仅当所有条目都是 `source`、`pointer` 或 `copy` 时 `ok=True`。
17+
- `main(argv=None) -> int`：
18+
- 恰好一个参数（目录）。否则向 stderr 打印用法并返回 2。
19+
- 向 stdout 打印 `ok=... files=... diverged=...`；`ok` 时返回 0，
20+
否则 1。
21+
22+
完成的标准是 `python verify.py starter` 以 0 退出且全部十一个测试通过。

‎courses/agent-rules-single-source/lessons/L01.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
id: course-agent-rules-l01
3+
type: course
4+
title: "Measure the drift you already have"
5+
summary: "Run the checker against the three scenario repositories and read drift as a test failure, not a vibe."
6+
lang: en-US
7+
content_version: 1
8+
status: reviewed
9+
reviewed_on: 2026-09-12
10+
---
11+
12+
# Measure the drift you already have
13+
14+
## Objective
15+
16+
Run the checker against the three scenario repositories and read drift as a test failure, not a vibe.
17+
18+
## The lesson
19+
20+
Run `python starter/rules_check.py scenario/drifted` — it says everything is fine. That is the bug: three files disagree about one behavior and nothing notices. Then run the verifier:
21+
22+
## Exercise
23+
24+
- Map each `verify.py --expect-failure` name to a real drift class: no source, no pointer detection, no drift reporting
25+
- Open `scenario/drifted/.cursorrules` and find the rules that contradict AGENTS.md
26+
27+
## Checkpoint
28+
29+
The lesson's commands run, and you can explain — in your own words — what failed and why.
30+
31+
## Expected evidence
32+
33+
The command transcript and your answers.

‎courses/agent-rules-single-source/lessons/L01_cn.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
id: course-agent-rules-l01
3+
type: course
4+
title: "量化你已经存在的漂移"
5+
summary: "对三个场景仓库运行检查器，把漂移读成测试失败，而不是一种感觉。"
6+
lang: zh-CN
7+
content_version: 1
8+
status: reviewed
9+
reviewed_on: 2026-09-12
10+
---
11+
12+
# 量化你已经存在的漂移
13+
14+
## 目标
15+
16+
对三个场景仓库运行检查器，把漂移读成测试失败，而不是一种感觉。
17+
18+
## 课程内容
19+
20+
运行 `python starter/rules_check.py scenario/drifted`——它说一切正常。这正是 bug：三个文件对同一行为各执一词，却没有任何东西察觉。然后运行验证器：
21+
22+
## 练习
23+
24+
- 把 `verify.py --expect-failure` 里的每个具名失败对应到一类真实漂移：无真源、无指针识别、无漂移报告
25+
- 打开 `scenario/drifted/.cursorrules`，找出与 AGENTS.md 矛盾的规则
26+
27+
## 检查点
28+
29+
本课的命令运行通过，并且你能用自己的话说清什么失败了、为什么。
30+
31+
## 预期证据
32+
33+
命令输出记录与你的回答。

‎courses/agent-rules-single-source/lessons/L02.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
id: course-agent-rules-l02
3+
type: course
4+
title: "Decide the source of truth"
5+
summary: "AGENTS.md becomes the one file agents read; everything else is a pointer or a copy — decide, then write it down."
6+
lang: en-US
7+
content_version: 1
8+
status: reviewed
9+
reviewed_on: 2026-09-12
10+
---
11+
12+
# Decide the source of truth
13+
14+
## Objective
15+
16+
AGENTS.md becomes the one file agents read; everything else is a pointer or a copy — decide, then write it down.
17+
18+
## The lesson
19+
20+
Read the repository's own AGENTS.md and `templates/AGENT_RULES.example.md`. The decision this course enforces: AGENTS.md is the source (the AAIF-governed, agent-native standard); CLAUDE.md and .cursorrules may only point at it. Write your repository's decision as one sentence — that sentence is your contract.
21+
22+
## Exercise
23+
24+
- List which of your rule files restate rules instead of pointing
25+
- Ask the agent to critique your sentence for ambiguity
26+
27+
## Checkpoint
28+
29+
The lesson's commands run, and you can explain — in your own words — what failed and why.
30+
31+
## Expected evidence
32+
33+
The command transcript and your answers.

0 commit comments

Comments
 (0)