Bỏ qua, đến phần nội dung

Viết harness ​

Harness là gói tham chiếu tới nhiều tài nguyên khác, kèm quy ước làm việc của tổ chức. Để làm được, bạn cần là Member trở lên trong tổ chức, và các tài nguyên định đưa vào harness phải đã phát hành trên Tara.

Harness gồm những gì? ​

Harness giống một bản phân phối: cài một harness là có trọn môi trường làm việc. Bên trong có danh sách agent, skill, prompt và kit kèm ràng buộc version. Có quy ước làm việc sẽ được chèn vào CLAUDE.md của dự án, cấu hình mặc định cho .claude/settings.json, và các tệp mẫu của dự án như .bandum.json.

Cấu trúc thư mục ​

text
harness-web/
├── .claude-plugin/
│   └── plugin.json
├── template/
│   ├── CLAUDE.md
│   ├── settings.json
│   └── .bandum.json
├── docs/
│   ├── cai-dat.md
│   └── su-dung.md
├── README.md
└── CHANGELOG.md

template/CLAUDE.md là bắt buộc, và harness phải có dependencies. Plugin không nạp CLAUDE.md ở gốc, nên bạn đặt toàn bộ quy ước trong template/.

Khai báo plugin.json ​

json
{
  "name": "harness-web",
  "version": "1.0.0",
  "description": "Môi trường phát triển web: agent theo vai trò và quy trình S/M/L",
  "author": { "name": "Nhóm Nền tảng" },
  "dependencies": [
    { "name": "agent-dev", "version": "~1.1.0" },
    { "name": "agent-reviewer", "version": "~1.1.0" },
    { "name": "skill-sdlc", "version": "^1.2.0" },
    { "name": "kit-scm-github", "version": "^1.3.0" }
  ],
  "metadata": {
    "forge": {
      "schema": 1,
      "type": "harness",
      "org": "acme",
      "owners": ["owner@example.com"],
      "roles": ["Dev", "Reviewer", "Test"],
      "engines": ["claude-code"],
      "status": "active",
      "model": "sonnet-std",
      "docs": [
        { "type": "install", "path": "docs/cai-dat.md", "title": "Hướng dẫn cài đặt" },
        { "type": "usage", "path": "docs/su-dung.md", "title": "Hướng dẫn sử dụng" }
      ]
    }
  }
}

Agent nên dùng ~1.1.0 để chỉ nhận bản vá và giữ môi trường ổn định. Skill và kit ít đổi giao diện thì dùng ^1.2.0 là hợp lý. Muốn lên minor mới của một agent, bạn phát hành version mới của harness, nhờ vậy môi trường của bạn chỉ đổi khi harness đổi.

model là alias model mặc định, tra trong catalog. Alias không có trong catalog thì Tara từ chối.

Viết template/CLAUDE.md ​

File này chứa quy ước sẽ vào CLAUDE.md của mọi dự án dùng harness. Bạn viết ngắn, theo kiểu mệnh lệnh, và mỗi điều phải kiểm được.

markdown
## Quy trình làm việc với AI (harness-web)

- Nhánh `feature/<MÃ-ISSUE>-<mô-tả>`; commit `<MÃ-ISSUE> <mô tả ngắn>`; không push thẳng lên nhánh chính.
- Mỗi issue gắn đúng một label `type: feature|bug|debt|risk`.
- Không đưa secret, token, dữ liệu khách hàng vào code, prompt hay commit.

Khi người dùng chạy ph init, Phillip chèn nội dung này vào một khối có đánh dấu phillip:begin … phillip:end. Chạy lại chỉ thay phần trong khối, còn phần người dùng tự viết ngoài khối được giữ nguyên.

Viết template/settings.json ​

Phillip gộp file này vào .claude/settings.json của dự án. Nó giữ giá trị người dùng đã đặt và hợp nhất các danh sách. Ví dụ dưới đây chặn đọc những thư mục sinh tự động để tiết kiệm ngữ cảnh.

json
{
  "permissions": {
    "deny": ["Read(./node_modules/**)", "Read(./dist/**)"]
  }
}

Tài liệu đi kèm ​

Kit và harness bắt buộc có tài liệu install và usage, còn loại khác thì chỉ khuyến nghị. Bạn khai báo trong metadata.forge.docs như ví dụ trên. Tara tách tài liệu khỏi gói cài, lưu theo version và đưa sha256 vào chữ ký số. Người dùng đọc bằng ph tara docs harness-web.

Kiểm tra, gửi và thử ​

Trước hết bạn kiểm tra rồi gửi.

bash
ph tara check ./harness-web
ph tara publish ./harness-web

Sau khi được duyệt, bạn thử trên một dự án sạch.

bash
ph init harness-web
ph tara list

Nếu mọi thứ đúng, ph tara list hiện đủ các version đã khóa trong phillip.lock, kể cả phụ thuộc gián tiếp.

Gặp lỗi thì xử lý ra sao? ​

Nếu Tara báo a harness needs template/CLAUDE.md, bạn thêm file đó và đừng đặt CLAUDE.md ở gốc. Báo dependency "…" is not on Tara (not released, or private) nghĩa là tài nguyên đó chưa phát hành hoặc đang private. Báo no version of "…" satisfies constraint "…" nghĩa là ràng buộc của bạn quá chặt so với các bản đã phát hành. Còn nếu có cảnh báo phụ thuộc không có ràng buộc, bạn thêm ~ hoặc ^.

Đọc thêm ​