BÀI VIẾT

Phần 3/6: Từ ý tưởng đến spec, plan và task

Spec là hợp đồng giữa bạn và agent. Bài này đi từ spec template và bảng Behaviour, qua bảng task có lệnh kiểm tra, đến code viết theo kiểu test trước với đồng hồ được inject, rồi thực hành spec 0002 với Claude Code và Codex.

Minh họa các worker phối hợp qua bộ điều phối, lưu trạng thái và kiểm tra bảo mật.

Đọc cùng AI

Chọn nội dung để sao chép và dán vào trợ lý AI. Không tự gửi dữ liệu. Nội dung CMS được chuyển sang Markdown; dùng Markdown gốc nếu có.

Muốn xem nhanh trước? Video tổng hợp cả series (21 phút) đi qua toàn bộ vòng lặp trên repo mẫu.

Đưa cho agent một câu “thêm thống kê click theo ngày cho shortener” thì agent sẽ thêm được một thứ gì đó. Rắc rối bắt đầu khi bạn phải quyết định thứ đó đã xong hay chưa. Route nào? Response trông ra sao? Những ngày không có click có nằm trong danh sách hay bị bỏ qua? Link đã hết hạn có còn được đếm không? Agent đã tự chọn câu trả lời cho từng câu hỏi đó, một cách lặng lẽ, và bạn chỉ biết nó chọn gì khi đọc hết cái diff.

Phần này nhằm loại bỏ chuyện đoán mò đó. Mình sẽ đưa một tính năng đi từ ý tưởng đến spec, từ spec đến bảng task, rồi từ bảng task đến code được viết theo kiểu test trước, mỗi lần một task. Spec là hợp đồng giữa bạn và agent: nó nói “xong” nghĩa là gì, dưới dạng máy kiểm tra được. Bảng task là kế hoạch bạn duyệt trước khi bất kỳ file nào thay đổi. Còn test là nơi hợp đồng đó trở thành thứ chạy được.

Mình dùng repo mẫu agentic-shortlink: trước hết là spec 0001 (link expiry) đã hoàn thành để làm ví dụ, sau đó là spec 0002 (daily click stats) để bạn tự làm với Claude Code và với Codex.

Cuối bài bạn sẽ có

  • Một spec template mà mỗi phần đều có nhiệm vụ rõ ràng, cùng bảng Behaviour có các dòng chuyển thành test theo tỷ lệ một đổi một.
  • Cách đọc một bảng task trước khi duyệt: file, lệnh kiểm tra, phụ thuộc, và những gì nằm ngoài phạm vi.
  • Một đồng hồ được inject, và lý do rõ ràng vì sao agent viết code liên quan đến thời gian cần có nó.
  • Spec 0002 được agent của bạn hiện thực, bằng plan mode với /implement-spec 0002 trong Claude Code, hoặc từng task một với Codex, ở chế độ tương tác hay headless.
  • Danh sách những điểm cần soát khi review lời giải tham khảo, và mẫu báo cáo ba phần bạn có thể yêu cầu sau mỗi task.

Chuẩn bị

Bạn cần repo đã được thiết lập như trong Phần 2: Setup repo cho Claude Code và Codex: Node 22, pnpm, repo đã clone và đã được trust trong Claude Code, Codex đã cài, và pnpm check chạy xanh. Các vai trò đứng sau quy trình này (planner, executor, reviewer) được giải thích ở Phần 1.

Kiểm tra: tại thư mục gốc của repo, trên nhánh main:

pnpm check
# ...
#  Test Files  2 passed (2)
#       Tests  13 passed (13)

Vì sao cần spec: agent cần một định nghĩa “xong” mà nó tự kiểm tra được

Agent làm việc theo vòng lặp: đọc, sửa, chạy thử, xem kết quả, lặp lại. Nó dừng khi tin rằng việc đã xong. Nếu định nghĩa “xong” chỉ nằm trong đầu bạn, agent sẽ thay bằng định nghĩa của riêng nó, thường là “code biên dịch được và cái test mình vừa viết chạy qua”. Đó là một ngưỡng thấp, và chính agent tự đặt ra ngưỡng đó.

Đây là những gì mình đã gặp với các prompt mơ hồ kiểu “thêm thống kê click theo ngày”. Không có gì là cố ý; mỗi điểm là một phỏng đoán hợp lý mà không ai yêu cầu:

  • Agent tự nghĩ ra route và cấu trúc response. Lần này bạn nhận /stats?period=day, lần sau lại là /api/links/:slug/daily.
  • Nó chỉ trả về những ngày có click, nên biểu đồ “7 ngày gần nhất” chỉ có ba cột và không có khoảng trống.
  • Nó lưu thêm user agent hoặc IP “để phân tích phong phú hơn”, và giờ bạn phải giải thích chuyện đó với người phụ trách quyền riêng tư.
  • Nó gọi new Date() ngay trong handler, và cái test nó viết chạy qua hôm nay nhưng hỏng ở lần chạy vắt qua nửa đêm UTC.
  • Nó báo “xong, mọi test đều pass” sau khi chỉ chạy đúng file test mới của mình.

Có spec, cùng agent đó nhận một nhiệm vụ khác hẳn. Route, tham số query, giới hạn của nó, body của response, mã lỗi và những thứ không được làm đều đã được viết ra. Mỗi hành vi là một ví dụ có đầu vào và đầu ra cụ thể, nên agent có thể biến nó thành test, còn bạn kiểm tra kết quả bằng cách đọc một bảng thay vì đoán ý agent. Khi agent nói “xong”, bạn đối chiếu báo cáo của nó với Definition of done từng dòng một.

Spec template, từng phần một

Mọi spec trong repo đều bắt đầu từ file này:

docs/specs/TEMPLATE.md

# NNNN: <feature name>

Status: draft | approved | done
Owner: <human who approves the plan>

## Problem

One paragraph: who needs this and why. No solution here.

## Scope

In:

- ...

Out (do not build):

- ...

## Behaviour

Describe the observable behaviour as concrete examples. Prefer request/response pairs.

| Given | When | Then |
| --- | --- | --- |
| ... | ... | ... |

## Definition of done

Every line must be checkable by a machine or by reading one file.

- [ ] Tests in `test/<file>.test.ts` cover every row of the Behaviour table
- [ ] `pnpm check` passes (lint, typecheck, tests)
- [ ] No change to existing response fields unless listed under Behaviour
- [ ] README API section updated

## Risk

Reversible? Data migration? Public contract change? Pick the review level from AGENTS.md.

## Notes for the agent

Files likely to change, patterns to follow, traps.

Mỗi phần trả lời một câu hỏi mà nếu thiếu, agent sẽ tự trả lời thay bạn:

SectionQuestion it answersWhat goes wrong without it
Status, OwnerIs this ready to build, and who approves the plan?Agents start on drafts; nobody owns the approval.
ProblemWho needs this and why?The agent optimises for the wrong user.
Scope: InWhat exactly gets built?Features grow while the agent works.
Scope: OutWhat must not be built, even if it looks useful?“Helpful” extras: extra columns, extra endpoints, backfill scripts.
BehaviourWhat is the observable result for a given input?No tests that match your intent; the agent tests its own guesses.
Definition of doneHow do we know it is finished?“Done” means “compiles”.
RiskHow much review does this need?A schema change gets the same review as a typo fix.
Notes for the agentWhich files, which patterns, which traps?The agent rediscovers the codebase and picks a different pattern.

Bảng Behaviour chính là danh sách test

Bảng Behaviour là phần quan trọng nhất. Mỗi dòng có dạng Given / When / Then: một trạng thái ban đầu, một hành động, một kết quả quan sát được. Hãy viết các dòng thành ví dụ cụ thể với giá trị thật, tốt nhất là cặp request và response. “Trả về thống kê” không phải là một dòng. “GET /api/links/promo/stats/daily?days=3 trả về 200 với ba object này” mới là một dòng.

Nguyên tắc mình theo: mỗi dòng trở thành ít nhất một test, và mỗi test đều truy ngược được về một dòng. Khi review, mình đặt các dòng ở một bên, tên test ở bên kia và nối chúng lại. Một dòng không có test là hành vi chưa được kiểm chứng. Một test không có dòng tương ứng thì hoặc spec đang thiếu một dòng, hoặc agent đang test thứ không ai yêu cầu.

Thêm hai nguyên tắc từ skill new-spec trong repo: có ít nhất hai dòng cho trường hợp lỗi (đầu vào sai, tài nguyên không tồn tại), và mỗi mục trong Definition of done phải kiểm tra được bằng máy hoặc bằng cách đọc một file. “Code sạch” thì không kiểm tra được. “pnpm check chạy qua” thì được.

Lưu ý: nếu ý tưởng chưa có spec, repo có sẵn một skill cho việc đó: /new-spec <mô tả ngắn> trong Claude Code sẽ đọc template và các spec hiện có, hỏi bạn tối đa năm câu, rồi viết bản nháp spec mà không đụng vào code. Trong phần này cả hai spec đều đã có, nên mình bỏ qua bước đó.

Ví dụ hoàn chỉnh: spec 0001, link expiry

Spec 0001 đã hoàn thành, nên nó cho thấy trọn con đường từ spec đến code có test. Đây là nội dung đúng như đã commit:

docs/specs/0001-link-expiry.md

# 0001: Link expiry

Status: done
Owner: maintainer

## Problem

Campaign links should stop working after a campaign ends. Today every link lives forever.

## Scope

In:

- Optional `expiresInDays` (1 to 365) when creating a link
- Expired links stop redirecting
- Stats show whether a link has expired

Out (do not build):

- Changing the expiry of an existing link
- Background cleanup of expired rows
- Time zones other than UTC

## Behaviour

| Given | When | Then |
| --- | --- | --- |
| now = 2026-01-01T00:00Z | `POST /api/links {url, expiresInDays: 7}` | 201, `expiresAt = 2026-01-08T00:00:00.000Z` |
| no `expiresInDays` | create | `expiresAt = null`, never expires |
| `expiresInDays: 0` or `366` | create | 400 `invalid_request` |
| link expires in 1 day | `GET /:slug` before expiry | 302 to the target URL |
| link expired (now >= expiresAt) | `GET /:slug` | 410 `{ "error": "expired" }`, click not counted |
| link expired | `GET /api/links/:slug` | 200 with `expired: true` |

## Definition of done

- [x] `test/expiry.test.ts` covers every row above, using an injected clock (no real timers)
- [x] `pnpm check` passes
- [x] Existing fields in responses unchanged; `expiresAt` and `expired` added
- [x] README API section updated

## Risk

Medium: adds a nullable column (`expires_at`) and a new status code on a public route. Reversible: the column is nullable and ignored by old code.

## Notes for the agent

- Inject time through `createApp({ now })`; never call `Date.now()` in route handlers.
- Keep the expiry check in one exported function (`isExpired`) so stats and redirect agree.

Có vài điểm đáng chú ý. Danh sách Out nêu tên ba thứ mà agent rất có thể tự thêm vào (sửa thời hạn, job dọn dẹp, múi giờ) và cấm chúng. Dòng Behaviour đầu tiên cố định đồng hồ (now = 2026-01-01T00:00Z), nên expiresAt mong đợi là một chuỗi chính xác, không phải “khoảng một tuần nữa”. Phần Notes chỉ cho agent cách xử lý thời gian và nơi đặt quy tắc hết hạn, đúng hai chỗ mà nếu không có hướng dẫn agent sẽ tự ứng biến.

Từ spec đến bảng task

Trước khi có dòng code nào, planner (một agent trong plan mode, chỉ được đọc) đã chuyển spec thành bảng sau, và owner đã duyệt nó:

docs/tasks/0001-link-expiry.md

# Tasks for spec 0001: link expiry

Generated by the planner (plan mode, read-only), approved by the owner before any code was written.
Each task is small enough for one agent run and has its own check.

| # | Task | Files | Check | Depends on |
| --- | --- | --- | --- | --- |
| T1 | Add nullable `expires_at` column and map it in `LinkRepo` | `src/db.ts`, `src/repo.ts` | `pnpm typecheck` | none |
| T2 | Accept `expiresInDays` in `POST /api/links`, compute `expiresAt` from the injected clock | `src/app.ts` | `pnpm vitest run test/expiry.test.ts -t "sets expiresAt"` | T1 |
| T3 | Add `isExpired`; return 410 on redirect and `expired` in stats; do not count clicks | `src/app.ts` | `pnpm vitest run test/expiry.test.ts` | T2 |
| T4 | Update README API section | `README.md` | review | T3 |
| T5 | Full gate | none | `pnpm check` | T1-T4 |

Parallelism: T1-T3 touch the same files, so they run in sequence in one worktree. T4 can run in parallel once T3's response shape is fixed.

Mỗi task có bốn đặc điểm giúp việc giao nó cho agent trở nên an toàn:

  1. Nhỏ. Vừa một lượt chạy tập trung. T1 chỉ là một cột và phần mapping; nó không kiêm luôn việc thêm route.
  2. Có danh sách file. Trước khi chạy, bạn đã biết những file nào được phép thay đổi. Diff đụng vào file nào khác là tín hiệu để dừng lại và hỏi vì sao.
  3. Lệnh kiểm tra là một câu lệnh. pnpm typecheck, hoặc một test được lọc bằng -t. Chỉ task README ghi “review”, vì đọc văn xuôi thì người làm tốt hơn test.
  4. Phụ thuộc. T2 cần cột của T1; T3 cần trường dữ liệu của T2.

Quyết định chạy song song như thế nào

Quy tắc rất đơn giản: các task dùng chung file thì chạy tuần tự; các task không chung file nào thì có thể chạy song song. T1 đến T3 đều đụng vào src/app.ts hoặc src/repo.ts, nên chúng chạy lần lượt trong cùng một worktree. Chạy song song sẽ tạo ra ba nhánh cùng sửa những hàm giống nhau, và lúc merge chính là lúc công sức của agent bị mất. T4 chỉ đụng vào README.md, nên có thể chạy song song với phần còn lại, miễn là T3 đã chốt cấu trúc response mà nó mô tả.

Hai cột Files và Depends on cộng lại cho bạn lịch chạy. Chạy task song song trong các worktree riêng là chủ đề của Phần 4.

Từ các dòng Behaviour đến test

Đây là file test của spec 0001:

test/expiry.test.ts

import { describe, expect, it } from "vitest";
import { makeApp } from "./helpers.js";

const DAY = 24 * 60 * 60 * 1000;

describe("link expiry (spec 0001)", () => {
  it("sets expiresAt from expiresInDays", async () => {
    const { post } = makeApp(new Date("2026-01-01T00:00:00Z"));
    const body = await (await post({ url: "https://example.com", expiresInDays: 7 })).json();
    expect(body.expiresAt).toBe("2026-01-08T00:00:00.000Z");
  });

  it("redirects before expiry and returns 410 after", async () => {
    const { app, post, advance } = makeApp();
    await post({ url: "https://example.com", slug: "soon", expiresInDays: 1 });
    expect((await app.request("/soon")).status).toBe(302);
    advance(DAY);
    expect((await app.request("/soon")).status).toBe(410);
  });

  it("does not count clicks on expired links", async () => {
    const { app, post, advance } = makeApp();
    await post({ url: "https://example.com", slug: "old", expiresInDays: 1 });
    advance(2 * DAY);
    await app.request("/old");
    const stats = await (await app.request("/api/links/old")).json();
    expect(stats).toMatchObject({ clicks: 0, expired: true });
  });
});

Và đây là phần đối chiếu mà reviewer nên làm, từng dòng một. Một số dòng được kiểm tra trong test/links.test.ts, file vốn đã chứa các test về tạo link và validation:

Behaviour rowTestStatus
now = 2026-01-01, expiresInDays: 7 gives expiresAt = 2026-01-08...expiry.test.ts: “sets expiresAt from expiresInDays”covered
no expiresInDays gives expiresAt = nulllinks.test.ts: “creates a link with a generated slug” asserts toBeNull()covered
expiresInDays: 0 or 366 gives 400 invalid_requestlinks.test.ts: “rejects invalid input” with expiresInDays: 0, status onlypartial
before expiry, GET /:slug gives 302expiry.test.ts: “redirects before expiry and returns 410 after”covered
expired, GET /:slug gives 410, click not countedsame test (410) and “does not count clicks on expired links”covered
expired, GET /api/links/:slug gives expired: true“does not count clicks on expired links” (toMatchObject)covered

Mình làm phần đối chiếu này trong lúc viết bài và phát hiện lỗ hổng ở dòng 3: giá trị 366 không được test, và test chỉ kiểm tra status chứ không kiểm tra mã invalid_request. Vậy mà ô Definition of done vẫn được đánh dấu. Code thực tế có chặn 366 (.max(365) trong zod schema), nên hôm nay không có gì hỏng, nhưng nếu ai đó đổi giới hạn này thì cũng không có gì bắt được. Đó chính là ý nghĩa của bài tập: một ô đã đánh dấu chỉ là một lời khẳng định, và việc đối chiếu dòng với test là cách bạn kiểm chứng nó. Việc này mất chừng hai phút. Mình cố ý để nguyên lỗ hổng này trong repo làm bài khởi động: thêm một case it.each([0, 366]) vào test/expiry.test.ts, kiểm tra luôn error: "invalid_request", rồi chạy cho nó pass.

Đồng hồ được inject, và vì sao agent cần nó

Mọi test ở trên đều dựng app qua cùng một helper:

test/helpers.ts

import { createApp } from "../src/app.js";
import { openDb } from "../src/db.js";
import { LinkRepo } from "../src/repo.js";

export const ADMIN_KEY = "test-admin-key";

export function makeApp(start = new Date("2026-01-01T00:00:00Z")) {
  let current = start;
  const repo = new LinkRepo(openDb(":memory:"));
  const app = createApp({
    repo,
    baseUrl: "http://sho.rt",
    adminApiKey: ADMIN_KEY,
    now: () => current,
  });
  const advance = (ms: number) => {
    current = new Date(current.getTime() + ms);
  };
  const post = (body: unknown) =>
    app.request("/api/links", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
    });
  return { app, repo, advance, post };
}

createApp nhận vào một hàm now. Ở production không truyền gì và dùng giá trị mặc định () => new Date(); còn test truyền một closure trỏ đến biến current và đẩy nó tới bằng advance(ms). Trong test, “một ngày sau” chỉ là một lời gọi hàm, không phải sleep, cũng không cần thư viện giả lập timer.

Với agent, điều này còn quan trọng hơn với người, vì ba lý do:

  1. Test tất định là tín hiệu phản hồi của agent. Agent lặp cho đến khi test xanh. Nếu test phụ thuộc đồng hồ thật, xanh có thể chỉ có nghĩa là “lúc chạy tình cờ là 10 giờ sáng”. Một test chập chờn không dạy agent được gì, và khi gặp test chập chờn, agent hay nới lỏng assertion cho đến khi nó qua.
  2. Các điểm biên trở nên test được. Hết hạn đúng tại now >= expiresAt, một click lúc 23:59 UTC so với 00:01, N ngày gần nhất tính đến hôm nay: với đồng hồ inject, mỗi trường hợp chỉ cần một dòng thiết lập. Với thời gian thật, chúng thường không được test luôn.
  3. Quy tắc kiểm tra được bằng máy. AGENTS.md ghi “never call Date.now() or new Date() in route handlers”, và phần quy tắc review xếp vi phạm này vào mức high. Bạn kiểm tra nó bằng grep chứ không cần tin lời ai.

Kiểm tra: new Date() duy nhất trong file route là tham số mặc định, và các test expiry đều qua:

grep -n "Date.now()\|new Date()" src/app.ts
# 26:export function createApp({ repo, baseUrl, adminApiKey, now = () => new Date() }: AppDeps) {

pnpm vitest run test/expiry.test.ts
#  Test Files  1 passed (1)
#       Tests  3 passed (3)

Bài tập: spec 0002, daily click stats

Giờ đến lượt bạn làm một tính năng. Spec 0002 nằm trên main với Status approved và mọi ô trong Definition of done đều chưa đánh dấu:

docs/specs/0002-daily-click-stats.md

# 0002: Daily click stats

Status: approved (exercise for readers; reference solution on branch `solution/0002-daily-stats`)
Owner: maintainer

## Problem

A single click counter cannot show whether a campaign is still getting traffic. Owners want clicks per day.

## Scope

In:

- Record each successful redirect with its UTC date
- `GET /api/links/:slug/stats/daily?days=N` returns the last N days (default 7, max 90), oldest first, including days with zero clicks

Out (do not build):

- Per-hour buckets, referrers, user agents, IP addresses (no personal data is stored)
- Backfilling history for clicks recorded before this change

## Behaviour

| Given | When | Then |
| --- | --- | --- |
| link `promo` clicked twice on 2026-01-01 and once on 2026-01-03; now = 2026-01-03 | `GET /api/links/promo/stats/daily?days=3` | 200 `{ "slug": "promo", "days": [{"date":"2026-01-01","clicks":2},{"date":"2026-01-02","clicks":0},{"date":"2026-01-03","clicks":1}] }` |
| no `days` param | same request | 7 entries |
| `days=0`, `days=91`, `days=abc` | same request | 400 `invalid_request` |
| unknown slug | same request | 404 `not_found` |
| expired link visited | `GET /:slug` | 410, no row recorded (same rule as spec 0001) |

## Definition of done

- [ ] New table `link_clicks (slug TEXT, day TEXT, clicks INTEGER, PRIMARY KEY (slug, day))`, created in `openDb`
- [ ] Redirect increments both `links.clicks` and today's `link_clicks` row in one transaction
- [ ] `test/daily-stats.test.ts` covers every row above with the injected clock
- [ ] Deleting a link deletes its daily rows
- [ ] `pnpm check` passes; README API section updated

## Risk

Medium: new table and a write on the hot redirect path. Reversible: the table can be dropped without touching `links`.

## Notes for the agent

- Use an upsert: `INSERT ... ON CONFLICT(slug, day) DO UPDATE SET clicks = clicks + 1`.
- Build the zero-filled day list in TypeScript, not SQL; keep it a pure function with its own unit test.

Hãy đọc nó một lượt theo cách agent sẽ đọc. Route, giá trị mặc định, giới hạn và thứ tự (cũ nhất trước) đều đã cố định. Những ngày không có click vẫn phải có mặt, nên một câu GROUP BY đơn thuần không thể là toàn bộ lời giải. Dữ liệu cá nhân bị loại trừ rõ ràng. Dòng về link hết hạn nối spec này với spec 0001. Phần Notes chỉ cách viết upsert và nơi đặt logic điền số 0.

Phần còn lại của bài đi theo sơ đồ dưới đây: bạn đưa spec cho một planner không có quyền sửa file, nhận lại câu hỏi và bảng task, duyệt nó, rồi từng task chạy theo kiểu test trước và báo cáo kèm bằng chứng.

Sơ đồ tuần tự: người dùng đưa spec 0002 cho planner trong plan mode, planner đọc code và AGENTS.md mà không sửa gì rồi trả về câu hỏi và bảng task, người dùng duyệt, sau đó với mỗi task executor viết test thất bại, viết code, nhận kết quả đỏ hoặc xanh từ test và báo cáo đã xong và đã kiểm chứng kèm lệnh; cuối cùng người dùng chạy pnpm check
Từ spec đến task: lập kế hoạch không sửa file, duyệt, rồi làm từng task một, test trước.

Bắt đầu trên một nhánh riêng để lời giải tham khảo không chen vào:

git switch main
git switch -c feat/0002-daily-stats

Kiểm tra: spec đã được duyệt và chưa có gì được xây dựng:

grep -n "Status" docs/specs/0002-daily-click-stats.md
# 3:Status: approved (exercise for readers; reference solution on branch `solution/0002-daily-stats`)

ls test
# expiry.test.ts  helpers.ts  links.test.ts

Chạy với Claude Code

Repo có sẵn một skill cho đúng việc này. Nó đủ ngắn để đọc hết, và bạn nên đọc, vì đây là quy trình agent sẽ làm theo:

.claude/skills/implement-spec/SKILL.md

---
name: implement-spec
description: Implement an approved spec from docs/specs end to end - plan, task table, test-first changes, full check, self-review. Use when asked to build a feature that has a spec.
argument-hint: "<spec number or path>"
---

Implement spec $ARGUMENTS.

## 1. Plan (no edits)

- Read the spec, AGENTS.md and every file the spec's Notes mention.
- Write `docs/tasks/<spec-file-name>.md` with a table: `# | Task | Files | Check | Depends on`. Each task fits one focused run and has a command that proves it is done.
- Mark which tasks can run in parallel (no shared files).
- Show the table and wait for the human to approve it.

## 2. Execute, one task at a time

For each task:

1. Write or extend the test for that task. Run it and confirm it fails for the right reason.
2. Make the smallest change that passes it.
3. Run the task's Check command. Do not move on while it is red.

## 3. Verify

- `pnpm check` must pass.
- If the change touches a route, start the server (`pnpm dev` with a temp `DATABASE_PATH`) and exercise one Behaviour row with curl-equivalent `app.request` in a test, not by hand.

## 4. Review

- Run the `reviewer` subagent, then pass its findings to the `refuter` subagent.
- Fix every CONFIRMED finding, re-run `pnpm check`.

## 5. Report

Tick the spec's Definition of done boxes that are now true. Then reply with:

- Done and verified: each item with the command that proved it
- Done, not verified: and why
- Skipped: and why
- Suggested commit message (Conventional Commits)

Do not push.

Phiên làm việc diễn ra như sau:

  1. Chạy claude tại thư mục gốc của repo.
  2. Nhấn Shift+Tab để chuyển qua các chế độ quyền cho đến khi plan mode được bật (file CLAUDE.md của repo ghi “Shift+Tab twice” tính từ chế độ mặc định). Trong plan mode, Claude được đọc và chạy các lệnh chỉ đọc, nhưng không được sửa file.
  3. Gõ /implement-spec 0002. Skill nhận 0002 qua $ARGUMENTS, đọc spec, AGENTS.md và các file mà phần Notes nhắc đến, rồi trả về bảng task như một kế hoạch. Vì plan mode chặn mọi thao tác sửa, bảng đến tay bạn dưới dạng đề xuất chứ chưa phải là file.
  4. Đọc bảng theo danh sách ở mục tiếp theo. Nếu có gì sai, nói thẳng bằng lời (“T2 quá lớn, tách phần schema ra khỏi thay đổi ở redirect”) và để nó sửa lại. Chỉ duyệt khi mọi mục trong danh sách đều đạt.
  5. Khi bạn duyệt, Claude rời plan mode, ghi file docs/tasks/0002-daily-click-stats.md và bắt đầu với T1.

Lúc duyệt, mình thường thêm một câu: “After each task, stop and give me the three-part report before starting the next one.” Skill vốn đã chạy từng task một; câu này làm cho điểm dừng trở nên tường minh, để bạn thấy từng lượt đỏ rồi xanh trước khi task sau xây tiếp lên trên.

Cần soát gì trong bảng task trước khi duyệt

Planner của bạn sẽ không tạo ra bảng giống hệt của mình, và cũng không cần phải giống. Đây là bảng mình sẽ duyệt cho spec 0002, để bạn có cái mà so sánh:

#TaskFilesCheckDepends on
T1Add pure utcDay, lastNDays, fillDays with unit testssrc/lib/days.ts, test/daily-stats.test.tspnpm vitest run test/daily-stats.test.ts -t "lastNDays"none
T2Add link_clicks table (cascade delete); recordClick(slug, day) in one transaction; dailyClicks; redirect passes today’s UTC daysrc/db.ts, src/repo.ts, src/app.ts, test/daily-stats.test.tspnpm vitest run test/daily-stats.test.ts -t "deletes daily rows" and pnpm vitest run test/expiry.test.tsT1
T3Add GET /api/links/:slug/stats/daily with zod-validated days (default 7, 1 to 90)src/app.ts, test/daily-stats.test.tspnpm vitest run test/daily-stats.test.tsT2
T4Update README API sectionREADME.mdreviewT3
T5Full gatenonepnpm checkT1-T4

Về chạy song song: T1, T2 và T3 đều thêm test vào test/daily-stats.test.ts, còn T2 và T3 cùng sửa src/app.ts, nên chúng chạy tuần tự. T4 có thể chạy song song với phần cuối của T3 khi cấu trúc response đã chốt. Bạn có thể tách T1 ra bằng cách đặt các test thuần vào file riêng, nhưng với những helper nhỏ như thế này, chạy tuần tự rẻ hơn chi phí phối hợp.

Dù nhận được bảng nào, hãy soát những điểm sau trước khi duyệt:

  • Mỗi dòng Behaviour đều nằm trong lệnh kiểm tra của một task nào đó. Spec 0002 có năm dòng; hãy tìm đủ cả năm.
  • Mỗi mục trong Definition of done đều có task tương ứng. Bảng dữ liệu, transaction, file test, xoá dây chuyền, pnpm check, README. Xoá dây chuyền là mục planner hay quên nhất.
  • Mỗi task đều có lệnh kiểm tra là một câu lệnh, trừ task tài liệu. “Kiểm tra thủ công” trên một task code nghĩa là task chưa xong cho đến khi chính bạn làm việc đó.
  • File khớp với cấu trúc của repo. SQL chỉ nằm trong src/repo.ts, schema trong src/db.ts, helper thuần trong src/lib/, route trong src/app.ts. Một task đặt câu query vào app.ts sẽ trượt review sau này; sửa ngay bây giờ rẻ hơn.
  • Phụ thuộc và file dùng chung phải khớp nhau. Nếu hai task cùng liệt kê một file thì chúng không song song, bất kể bảng ghi gì.
  • Phạm vi Out được tôn trọng. Không có bucket theo giờ, không có cột referrer hay user agent, không có địa chỉ IP, không có script backfill. Cũng không thêm dependency: một thư viện ngày tháng để tính “N ngày gần nhất” là vi phạm quy tắc 4 trong AGENTS.md (“no new dependencies without asking”).
  • Mỗi task vừa một lượt chạy. Nếu mô tả task có ba chữ “và” và năm file, hãy yêu cầu tách ra.

Kiểm tra: ngay sau khi duyệt, chỉ có file task là mới. Không có gì trong src/ được phép thay đổi trước khi file task tồn tại:

git status --short
# ?? docs/tasks/0002-daily-click-stats.md

Test trước, mỗi lần một task

Với mỗi task, skill yêu cầu cùng ba bước: viết test, chạy và thấy nó thất bại vì đúng lý do, rồi làm thay đổi nhỏ nhất để test qua và chạy lệnh Check của task. “Vì đúng lý do” là điểm quan trọng. Với T2, thất bại đúng là vì dailyClicks hoặc bảng link_clicks chưa tồn tại. Một thất bại do gõ nhầm trong test hay lỗi import thì không chứng minh được gì về tính năng. Hãy yêu cầu agent cho bạn xem thông báo lỗi, chứ không chỉ nói “nó đã fail”.

Sau T5, skill chạy subagent reviewer trên diff, chuyển các phát hiện của nó cho subagent refuter, rồi sửa những gì còn đứng vững. Phần 5 nói về cặp này trong CI; ở đây nó chạy cục bộ trước khi bạn nhận báo cáo cuối.

Kiểm tra: khi agent báo xong. Số test của bạn có thể khác nếu agent viết nhiều hoặc ít test hơn; lời giải tham khảo cho ra các con số sau:

pnpm vitest run test/daily-stats.test.ts
#  Test Files  1 passed (1)
#       Tests  10 passed (10)

pnpm check
#  Test Files  3 passed (3)
#       Tests  23 passed (23)

Chạy với Codex

Codex đọc cùng file AGENTS.md, nên các quy tắc giống hệt nhau. Repo này không có skill implement-spec cho Codex, nên quy trình phải nằm trong prompt của bạn. Cấu hình dự án (.codex/config.toml) đặt sandbox_mode = "workspace-write" và approval_policy = "on-request", nghĩa là Codex được sửa file trong repo mà không cần hỏi. Câu “Do not edit yet” trong prompt là một lời đề nghị, không phải một cái khoá.

Chế độ tương tác

Chạy codex tại thư mục gốc của repo và gửi prompt lập kế hoạch:

Read docs/specs/0002-daily-click-stats.md and AGENTS.md. Do not edit yet.
Propose docs/tasks/0002-daily-click-stats.md in the same format as
docs/tasks/0001-link-expiry.md: a table with # | Task | Files | Check | Depends on.
Each task must fit one focused run and have a command as its check.
Mark which tasks can run in parallel (no shared files).
List anything in the spec that is ambiguous as questions for me.

Soát bảng theo đúng danh sách ở trên. Khi đã ổn, bảo Codex ghi file, rồi chạy từng task, mỗi task một tin nhắn:

Write the approved table to docs/tasks/0002-daily-click-stats.md. Do not touch other files.

Do T1 from docs/tasks/0002-daily-click-stats.md. Restate it as concrete outputs first.
Write the test first and show me it failing, then make it pass.
Run the task's Check command. Stop and report: done and verified (with the command),
done but not verified, skipped.

Lặp lại tin nhắn thứ hai cho T2, T3 và các task tiếp theo. Đọc từng báo cáo trước khi giao task kế tiếp.

Chế độ headless

Nếu bạn muốn bước lập kế hoạch được cưỡng chế thay vì chỉ được yêu cầu, hãy dùng codex exec cho bước đó. Sandbox mặc định của nó là read-only, nên nó không thể ghi file dù có muốn. Tuỳ chọn -o lưu tin nhắn cuối cùng, chính là bảng task:

mkdir -p agent-runs

codex exec "Read docs/specs/0002-daily-click-stats.md and AGENTS.md. Do not edit. \
Propose docs/tasks/0002-daily-click-stats.md in the format of docs/tasks/0001-link-expiry.md \
(# | Task | Files | Check | Depends on), mark parallel tasks, and list open questions." \
  -o agent-runs/0002-plan.md

Đọc agent-runs/0002-plan.md, sửa những chỗ bạn không đồng ý, rồi tự lưu bảng thành docs/tasks/0002-daily-click-stats.md. Bạn là người duyệt; việc lưu file chính là hành động duyệt. Sau đó chạy từng task với quyền ghi:

codex exec "Do T1 from docs/tasks/0002-daily-click-stats.md. Follow AGENTS.md. \
Restate the task first, write the test first and confirm it fails, then make it pass. \
Run the task's Check. End with: done and verified (with commands), done but not verified, skipped." \
  --sandbox workspace-write \
  -o agent-runs/0002-T1.md

agent-runs/ nằm trong .gitignore, nên các báo cáo không bao giờ lọt vào commit. Thêm --json nếu bạn muốn nhận toàn bộ luồng sự kiện trên stdout để ghi log. Ở Phần 4, scripts/agent-task.sh bọc chính lời gọi này và cho mỗi task một worktree và một nhánh riêng.

Kiểm tra: sau mỗi task chạy headless, file báo cáo phải tồn tại và lệnh kiểm tra của task phải xanh khi chính bạn chạy lại:

cat agent-runs/0002-T1.md
pnpm vitest run test/daily-stats.test.ts -t "lastNDays"
# all selected tests pass, 0 failed
git status --short
# only the files listed for T1

Đọc lời giải tham khảo bằng con mắt của reviewer

Khi phiên bản của bạn đã xanh, hãy so nó với nhánh solution/0002-daily-stats. Đừng xem trước; mục đích là tập review công việc của agent, và lời giải tham khảo chỉ là một đáp án tốt chứ không phải đáp án duy nhất.

git diff --stat main solution/0002-daily-stats
git show solution/0002-daily-stats:src/lib/days.ts

Các helper thuần

src/lib/days.ts (nhánh solution)

const DAY_MS = 24 * 60 * 60 * 1000;

export function utcDay(date: Date): string {
  return date.toISOString().slice(0, 10);
}

export function lastNDays(now: Date, n: number): string[] {
  const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
  return Array.from({ length: n }, (_, i) => utcDay(new Date(today - (n - 1 - i) * DAY_MS)));
}

export function fillDays(days: string[], counts: Map<string, number>) {
  return days.map((date) => ({ date, clicks: counts.get(date) ?? 0 }));
}

Ba hàm nhỏ, không có database, không có đồng hồ. lastNDays nhận now làm tham số, nên nơi gọi quyết định bây giờ là mấy giờ. fillDays chính là phần điền số 0 mà spec yêu cầu, viết bằng một phép map đơn giản trên danh sách ngày. Vì là hàm thuần, chúng có unit test đơn giản với đầu vào cố định, và những test đó là nơi rẻ nhất để bắt lỗi lệch một ngày trong khoảng thời gian.

Schema và repo

src/db.ts (nhánh solution)

import Database from "better-sqlite3";

export type Db = Database.Database;

export function openDb(path: string): Db {
  const db = new Database(path);
  db.pragma("journal_mode = WAL");
  db.exec(`
    CREATE TABLE IF NOT EXISTS links (
      slug        TEXT PRIMARY KEY,
      url         TEXT NOT NULL,
      created_at  TEXT NOT NULL,
      expires_at  TEXT,
      clicks      INTEGER NOT NULL DEFAULT 0
    );
    CREATE TABLE IF NOT EXISTS link_clicks (
      slug    TEXT NOT NULL REFERENCES links(slug) ON DELETE CASCADE,
      day     TEXT NOT NULL,
      clicks  INTEGER NOT NULL DEFAULT 0,
      PRIMARY KEY (slug, day)
    );
  `);
  db.pragma("foreign_keys = ON");
  return db;
}

src/repo.ts (nhánh solution, hai method mới)

// ...
  recordClick(slug: string, day: string): void {
    this.db.transaction(() => {
      this.db.prepare("UPDATE links SET clicks = clicks + 1 WHERE slug = ?").run(slug);
      this.db
        .prepare(
          `INSERT INTO link_clicks (slug, day, clicks) VALUES (?, ?, 1)
           ON CONFLICT(slug, day) DO UPDATE SET clicks = clicks + 1`,
        )
        .run(slug, day);
    })();
  }

  dailyClicks(slug: string, fromDay: string, toDay: string): Map<string, number> {
    const rows = this.db
      .prepare("SELECT day, clicks FROM link_clicks WHERE slug = ? AND day BETWEEN ? AND ?")
      .all(slug, fromDay, toDay) as { day: string; clicks: number }[];
    return new Map(rows.map((r) => [r.day, r.clicks]));
  }
  // ...

Route

src/app.ts (nhánh solution: query schema, route mới và đoạn redirect đã thay đổi)

// ...
const DailyStatsQuery = z.object({
  days: z.coerce.number().int().min(1).max(90).default(7),
});
// ...
  app.get("/api/links/:slug/stats/daily", (c) => {
    const query = DailyStatsQuery.safeParse({ days: c.req.query("days") });
    if (!query.success) {
      return c.json({ error: "invalid_request", issues: query.error.issues }, 400);
    }
    const link = repo.find(c.req.param("slug"));
    if (!link) return c.json({ error: "not_found" }, 404);
    const days = lastNDays(now(), query.data.days);
    const counts = repo.dailyClicks(link.slug, days[0] ?? "", days.at(-1) ?? "");
    return c.json({ slug: link.slug, days: fillDays(days, counts) });
  });
  // ...
  app.get("/:slug", (c) => {
    const link = repo.find(c.req.param("slug"));
    if (!link) return c.json({ error: "not_found" }, 404);
    if (isExpired(link, now())) return c.json({ error: "expired" }, 410);
    repo.recordClick(link.slug, utcDay(now()));
    return c.redirect(link.url, 302);
  });
// ...

Test

test/daily-stats.test.ts (nhánh solution, đã rút gọn)

import { describe, expect, it } from "vitest";
import { fillDays, lastNDays } from "../src/lib/days.js";
import { ADMIN_KEY, makeApp } from "./helpers.js";

const DAY = 24 * 60 * 60 * 1000;

// ... describe("lastNDays / fillDays"): two unit tests for the pure helpers

describe("GET /api/links/:slug/stats/daily (spec 0002)", () => {
  it("returns zero-filled daily clicks, oldest first", async () => {
    const { app, post, advance } = makeApp(new Date("2026-01-01T10:00:00Z"));
    await post({ url: "https://example.com", slug: "promo" });
    await app.request("/promo");
    await app.request("/promo");
    advance(2 * DAY);
    await app.request("/promo");

    const res = await app.request("/api/links/promo/stats/daily?days=3");
    expect(res.status).toBe(200);
    expect(await res.json()).toEqual({
      slug: "promo",
      days: [
        { date: "2026-01-01", clicks: 2 },
        { date: "2026-01-02", clicks: 0 },
        { date: "2026-01-03", clicks: 1 },
      ],
    });
  });
  // ... "defaults to 7 days", "rejects days=0/91/abc", "returns 404 for unknown slugs"

  it("does not record clicks on expired links", async () => {
    const { app, post, advance } = makeApp(new Date("2026-01-01T00:00:00Z"));
    await post({ url: "https://example.com", slug: "old", expiresInDays: 1 });
    advance(DAY);
    expect((await app.request("/old")).status).toBe(410);
    const body = await (await app.request("/api/links/old/stats/daily?days=2")).json();
    expect(body.days.every((d: { clicks: number }) => d.clicks === 0)).toBe(true);
  });

  it("deletes daily rows with the link", async () => {
    const { app, post, repo } = makeApp(new Date("2026-01-01T00:00:00Z"));
    await post({ url: "https://example.com", slug: "tmp" });
    await app.request("/tmp");
    await app.request("/api/links/tmp", { method: "DELETE", headers: { "x-api-key": ADMIN_KEY } });
    expect(repo.dailyClicks("tmp", "2026-01-01", "2026-01-01").size).toBe(0);
  });
});

Reviewer cần soát những gì

  • Transaction. recordClick bọc lệnh cập nhật bộ đếm và lệnh upsert trong this.db.transaction(...)(). Để ý cặp () ở cuối: transaction của better-sqlite3 trả về một hàm, quên gọi nó thì không có gì chạy cả. Không có transaction, một lỗi xảy ra giữa hai câu lệnh sẽ khiến links.clicks và các dòng theo ngày lệch nhau.
  • Upsert dùng tham số bind. ON CONFLICT(slug, day) DO UPDATE SET clicks = clicks + 1, với placeholder ?, nằm trong src/repo.ts. SQL ở bất kỳ chỗ nào khác, hoặc được ghép bằng nối chuỗi, là phát hiện mức high theo AGENTS.md.
  • Điền số 0 là một hàm thuần. SQL chỉ trả về những ngày có dữ liệu; fillDays thêm những ngày còn thiếu bằng TypeScript, đúng như Notes yêu cầu. Nếu agent của bạn làm việc này bằng recursive CTE, có thể nó vẫn chạy đúng, nhưng nó đã bỏ qua một Note, và điều đó đáng để hỏi lại.
  • Link hết hạn không được ghi nhận. Trong redirect, lệnh return 410 đứng trước recordClick. Đảo hai dòng đó là link hết hạn bắt đầu được đếm. Test “does not record clicks on expired links” sẽ fail nếu chúng bị đảo.
  • Xoá dây chuyền cần pragma. ON DELETE CASCADE trong schema không có tác dụng gì trong SQLite trừ khi foreign_keys được bật cho kết nối đó, mà mặc định nó tắt. Chính db.pragma("foreign_keys = ON") trong openDb làm cho mục “Deleting a link deletes its daily rows” trở thành sự thật. Test “deletes daily rows with the link” là bằng chứng; thiếu pragma thì test này fail.
  • Thời gian được inject. Route và redirect gọi now(), không bao giờ gọi new Date(). Hãy chạy lại lệnh grep ở trên với phiên bản của bạn.
  • Thứ tự validation. Lời giải tham khảo validate days trước khi tìm slug, nên /api/links/nope/stats/daily?days=abc trả về 400 chứ không phải 404. Spec không nói bên nào thắng. Chấp nhận như vậy là được, nhưng nếu điều này quan trọng với bạn, cách sửa là thêm một dòng Behaviour mới, không phải lặng lẽ đổi code.

Kiểm tra: tự chạy lời giải tham khảo và so số test với của bạn:

git stash -u   # only if you have uncommitted work
git switch solution/0002-daily-stats
pnpm check
#  Test Files  3 passed (3)
#       Tests  23 passed (23)
git switch feat/0002-daily-stats

Nhắc lại nhiệm vụ trước, báo cáo theo ba phần

Hai dòng trong mục “How to work” của AGENTS.md gánh phần lớn việc giữ cho agent trung thực:

2. Restate the task as concrete outputs (files, endpoints, status codes) before editing. Build exactly that. Offer extras in one line; do not build them.
...
5. Finish with a summary in three parts: done and verified (with the command you ran), done but not verified, skipped.

Nhắc lại nhiệm vụ nghĩa là trước khi sửa, agent viết ra đúng nguyên văn các đầu ra của task: file nào, hàm nào, route nào, status code nào. Đây là một điểm kiểm soát rất rẻ. Nếu phần nhắc lại của T2 ghi “add a link_clicks table with a user_agent column”, bạn chặn nó ngay tại đó, chứ không phải sau khi migration đã chạy. Một bản nhắc lại tốt cho T2 trông như sau:

T2, restated:
- src/db.ts: new table link_clicks (slug, day, clicks, PRIMARY KEY (slug, day)),
  slug references links(slug) ON DELETE CASCADE; foreign_keys pragma on in openDb
- src/repo.ts: recordClick(slug, day) updates links.clicks and upserts today's
  link_clicks row in one transaction; new dailyClicks(slug, fromDay, toDay)
- src/app.ts: GET /:slug passes utcDay(now()) to recordClick; nothing else changes
- test/daily-stats.test.ts: "deletes daily rows with the link"
Not in T2: the stats route (T3), README (T4).

Báo cáo ba phần tách bạch những gì agent đã chứng minh với những gì nó chỉ tin là đúng. Đây là báo cáo mình sẽ chấp nhận cho T2. Nó là ví dụ về định dạng do mình viết tay, không phải log thu được từ một lượt chạy:

Done and verified
- Daily rows are deleted with their link:
  pnpm vitest run test/daily-stats.test.ts -t "deletes daily rows"
  (failed first: link_clicks did not exist; passes now)
- Redirect and expiry behaviour unchanged:
  pnpm vitest run test/expiry.test.ts (3 passed)
- Types: pnpm typecheck (no errors)

Done, not verified
- Atomicity of recordClick: no test forces the second statement to fail;
  checked by reading the transaction wrapper in src/repo.ts.

Skipped
- Stats route and its tests (T3), README (T4), full pnpm check (T5).

Điều làm nên một báo cáo tốt: mỗi dòng “đã kiểm chứng” đều kèm lệnh đã dùng để kiểm chứng, trình tự đỏ rồi xanh được nêu rõ, phần chưa kiểm chứng được gọi tên thay vì bị giấu đi, và mục “bỏ qua” chỉ đến những task chịu trách nhiệm cho các mục đó. Một báo cáo chỉ ghi “Implemented T2, all tests pass” không cho bạn thứ gì để kiểm tra. Hãy yêu cầu viết lại.

Khi xong toàn bộ spec, skill còn đánh dấu những ô Definition of done nay đã đúng. Hãy đối chiếu từng ô với diff, giống như cách mình đã đối chiếu các dòng của spec 0001. Ô được đánh dấu bởi chính agent đã làm việc đó, nên nó vẫn chỉ là lời khẳng định cho đến khi bạn tự xem.

Những lỗi hay gặp

Duyệt kế hoạch mà task không có lệnh kiểm tra

Một task không có lệnh kiểm tra là task mà việc hoàn thành chỉ là ý kiến của agent. Planner sẽ rất sẵn lòng ghi “verify the endpoint works”. Hãy trả lại và yêu cầu đúng dòng pnpm vitest run ... -t "...". Nếu chưa có test nào kiểm tra được task đó, nhiều khả năng task đang có kích thước sai.

Task quá lớn cho một lượt chạy

“Implement daily stats” làm T1 không phải là kế hoạch; đó là prompt ban đầu có thêm con số ở phía trước. Task dài sẽ trôi dần khi context của agent đầy lên bởi output của các bước trước. Một tín hiệu hữu ích là cột Files. Hơn ba bốn file, hoặc file thuộc nhiều tầng khác nhau, thường có nghĩa là hai task.

Để agent lặng lẽ sửa spec

Khi một test khó làm cho qua, đôi khi agent sẽ “sửa” spec: bỏ một dòng Behaviour, đổi một giới hạn, đánh dấu một ô chưa đúng. Spec là hợp đồng, nên mọi thay đổi trên nó phải qua tay bạn. Hãy chạy git diff main -- docs/specs/ sau mỗi lượt; thay đổi duy nhất được chờ đợi là các ô được đánh dấu. Nếu agent phát hiện một vấn đề thật trong spec, nó nên nêu ra trong báo cáo và chờ.

Test gọi thời gian thật

Một agent không biết đến makeApp(start) và advance(ms) sẽ viết new Date() trong test, hoặc tìm đến một thư viện giả lập timer. Test chạy qua hôm nay và hỏng ở lần chạy vắt qua nửa đêm UTC. Spec ghi “with the injected clock” trong Definition of done là có lý do. Hãy grep file test mới để tìm new Date() không có tham số và Date.now().

Bỏ qua phần “Out of scope”

Một danh sách Out để trống là một lời mời. Với thống kê theo ngày, những thứ dễ bị thêm vào nhất là bucket theo giờ, referrer và user agent, và mỗi thứ đều là một quyết định về quyền riêng tư hoặc lưu trữ, không nên để agent tiện tay quyết định. Hãy viết danh sách Out kể cả khi nó có vẻ hiển nhiên, và đối chiếu kế hoạch với nó.

Tin vào hook trước khi workspace được trust

Khi xây dựng repo này, mình thấy Claude Code bỏ qua toàn bộ .claude/settings.json, cả permission lẫn hook, cho đến khi mình mở repo ở chế độ tương tác và chấp nhận hộp thoại trust. Trước đó, một lệnh thử git add -A vẫn chạy; sau khi trust, guard hook chặn nó với thông báo “Blocked by .claude/hooks/guard-bash.mjs: stage files explicitly”. Với một bản clone mới, hãy mở nó ở chế độ tương tác một lần trước khi chạy bất cứ thứ gì headless.

Checklist

  • Spec có Status approved, có Owner, có danh sách Out đầy đủ, và các dòng Behaviour với giá trị cụ thể, trong đó có ít nhất hai dòng cho trường hợp lỗi.
  • Mỗi mục trong Definition of done đều kiểm tra được bằng một lệnh hoặc bằng cách đọc một file.
  • Kế hoạch được lập trong plan mode (Claude Code) hoặc trong sandbox read-only (codex exec), và không có gì trong src/ thay đổi trước khi bạn duyệt.
  • Mỗi task trong bảng đều có file, lệnh kiểm tra và phụ thuộc; các task dùng chung file chạy tuần tự.
  • Kế hoạch tôn trọng phần Out of scope và không thêm dependency.
  • Mỗi task đã nhắc lại đầu ra trước khi sửa, và cho thấy test thất bại trước khi viết code.
  • Test dùng makeApp(start) và advance(ms); không có thời gian thật trong test hay handler.
  • Mỗi task kết thúc bằng báo cáo ba phần kèm lệnh.
  • Bạn đã tự đối chiếu mọi dòng Behaviour với test, và soát mọi ô đã đánh dấu với diff.
  • git diff main -- docs/specs/ chỉ cho thấy các ô được đánh dấu.
  • pnpm check xanh.

Ở phần tiếp theo, mình sẽ lấy bảng task này và chạy các task song song, mỗi task trong một worktree riêng, và chuyển một số task sang các provider khác nhau.

Trong series này

  1. Kiến trúc và vai trò của các model
  2. Setup repo cho Claude Code và Codex
  3. Spec, kế hoạch và task
  4. Làm song song và dùng nhiều provider
  5. CI/CD với AI review
  6. Vận hành: chi phí, bảo mật và học hỏi
  7. Phần 7: Áp dụng quy trình agent vào một dự án thật

Repo mẫu cho cả series nằm tại github.com/luonghongthuan/agentic-shortlink. Spec 0002 là bài tập trên main; lời giải tham khảo nằm trên nhánh solution/0002-daily-stats.

Thảo luận

Bình luận được duyệt trước khi công khai. Email của bạn được giữ riêng tư.

← Về danh sáchRead in English