harness-agile

多條探索路徑穿過檢查點，逐步收斂成可交付成果。

CI Git tag PyPI npm Python Claude Code + Codex

讓 Claude Code 與 Codex 沿用同一份需求、規格與交付紀錄。

繁體中文 · English

harness-agile 是一份可攜的 AI 協作開發範本。從釐清需求到合併變更，每一步都有工作指引、產出與檢查條件；換工具或交接時，下一位開發助理可以接著同一份紀錄工作。

適合想把 AI 開發流程納入 Git、需要在 Claude Code 與 Codex 之間交接的個人或團隊。範本提供協作骨架，產品的技術棧與功能由你決定。

你會得到什麼

  • 一份共用規範。 AGENTS.md 保存專案目的與工作流程，兩套工具共用 skills 正本，各自保留原生工具與角色設定。
  • 可追溯的交付紀錄。 需求寫成 spec，驗收條件對應到 tickets；review、測試與尚未解決的問題一起留在 repository。
  • 可搬移的專案。 建立器攜帶範本資料，skills 支援相對 symlink 或完整副本，並記錄採用來源與內容 digest。

快速開始

準備 uv，然後在新專案的父目錄執行：

uvx --from 'harness-agile==0.2.1' \
  harness-agile init my-project --name '我的專案' \
  --one-liner '它要解決的問題。' --no-input
cd my-project
uv run --python 3.11 python scripts/verify-project.py

這會建立專案目錄、填入名稱與描述，並檢查協作設定。目標須不存在或為空，父目錄須已存在。指令從 PyPI 安裝固定版本，不需要 GitHub 帳號。

接著在新目錄開啟 Claude Code 或 Codex，執行 grill-with-docs，定義 AGENTS.md 裡的 Project Charter：產品服務誰、解決什麼問題、必須做到什麼。名稱與一句話描述只是起點，尚未代表需求確認。

操作 Claude Code Codex
定義 Project Charter /grill-with-docs $grill-with-docs
查看可用 skills /skills /skills
審查變更 /code-review $code-review
使用 npx 或 pnpx

需要 Node.js 18+，以及 Python 3.11+ 或 uv。

npx --yes --package='create-harness-agile@0.2.1' \
  create-harness-agile init my-project --name '我的專案' \
  --one-liner '它要解決的問題。' --no-input

pnpx 'create-harness-agile@0.2.1' \
  init my-project --name '我的專案' --one-liner '它要解決的問題。' --no-input

pnpx 也可換成 pnpm dlx。三個入口使用同一套 Python 初始化邏輯；uvx 從 PyPI 安裝 harness-agile，npx／pnpx 從 npm 安裝 create-harness-agile。Node 入口先尋找 Python，再使用 uv；可用 HARNESS_PYTHON 指定 Python 執行檔。

已複製 GitHub template、要從本機建立，或需要預覽與完整參數，請讀採用指引。要請開發助理代為建立，提供 INSTALL.md、目標目錄、名稱與一句話描述即可。

從想法到交付

先完成 walking skeleton：讓最薄的一條產品路徑真正跑通，建立後續開發可用的接點。這是第 0 輪，免 spec 與規格 review；合併到 main 後，後續以 epic 交付可展示的增量。

釐清需求 → spec＋追溯矩陣 → 四軸 review → tickets → TDD
        → code review → security review → 實際介面驗證 → 合併

使用者在需求共識、拆票及測試計畫等節點確認方向。每張 ticket 使用獨立分支；驗證必須涵蓋功能真正執行的介面。完整規則見交付流程，日常操作見協作指南。

文件導覽

你想做的事 從這裡開始
建立新專案、選擇初始化方式 採用指引
使用 skills、換工具、交接工作 協作指南
讓開發助理執行建立程序 INSTALL.md（英文）
查閱流程、tracker、review 規則 共用規範與執行文件
修改母範本、驗證變更 貢獻與維護

開發與驗證

在尚未初始化的母範本中，使用 Python 3.11+：

python3 scripts/verify-project.py
python3 -m unittest discover -s tests -v

這些檢查涵蓋範本結構、skills 與初始化行為。產品功能測試由 walking skeleton 建立；CI badge 連結到遠端執行狀態，不代表新產品功能已通過驗證。

授權

本專案採用 MIT License。內附第三方 skills、字型與品牌素材保留各自的授權；適用範圍及來源見第三方聲明與來源紀錄。

範本設計與歷程

維護文件索引保存設計背景、研究、計畫與歷史驗證。預設初始化會移除這些資料、範本 banner 與英文 README，並將本頁改為產品 README；--keep-template-files 可保留範本文件。

Windows 的 Archify 自動開啟功能已停用；圖表產生與驗證仍可使用，請手動開啟產物。詳見停用範圍與驗證方式。

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for cxph03n1x from gravatar.com cxph03n1x

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

harness_agile-0.2.1.tar.gz (4.0 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

harness_agile-0.2.1-py3-none-any.whl (4.0 MB view details)

Uploaded Python 3

File details

Details for the file harness_agile-0.2.1.tar.gz.

File metadata

  • Download URL: harness_agile-0.2.1.tar.gz
  • Upload date:
  • Size: 4.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for harness_agile-0.2.1.tar.gz
Algorithm Hash digest
SHA256 04c68f065b7a44c878ea595d1f028742b5bb8a933141c6ae2913c579c9704f64
MD5 0bc95afdaf36e2a2a370ec7bbb2eb138
BLAKE2b-256 99c3f842835e5d562b2fd188f72b2e99708fec8e77992039072a7230d1174795

See more details on using hashes here.

Provenance

The following attestation bundles were made for harness_agile-0.2.1.tar.gz:

Publisher: publish-pypi.yml on CXPhoenix/harness-agile

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file harness_agile-0.2.1-py3-none-any.whl.

File metadata

  • Download URL: harness_agile-0.2.1-py3-none-any.whl
  • Upload date:
  • Size: 4.0 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for harness_agile-0.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 7d6d8a509c03f3d3e7197b7bad0ce188266b241d320d87a72a0f71204844a402
MD5 0c5d695693d5502947c975fa600ffa66
BLAKE2b-256 7e8420c3962a1046a435057a3f98524c01cbd443e467b4ec3065bd0bab6bd50c

See more details on using hashes here.

Provenance

The following attestation bundles were made for harness_agile-0.2.1-py3-none-any.whl:

Publisher: publish-pypi.yml on CXPhoenix/harness-agile

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 files

0.2.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page