Quản trị spec và plan AI trong Git: năm quy tắc, drift gate, nguồn và checklist

TL;DR

• Hãy commit các spec và plan do AI viết. Mọi công cụ đều đã làm vậy theo mặc định; câu hỏi còn lại là quản trị chúng.
• Mỗi squad một thư mục riêng với một dòng CODEOWNERS, để mỗi thay đổi spec tự động yêu cầu review từ chủ sở hữu code.
• Đặt header kiểu ADR trên mọi spec dùng chung: status, superseded-by, owner, các path liên quan, ngày review. Đừng bao giờ viết lại một spec đã accepted thành một quyết định mới.
• Chạy drift gate trong CI: với mỗi spec đã accepted, làm build fail khi một path mà spec nhắc tới không còn tồn tại.
• Đổi đường dẫn đầu ra bằng một dòng mệnh lệnh in đậm trong CLAUDE.md, giữ plan cá nhân trong CLAUDE.local.md và .git/info/exclude, và luôn ghi trên một branch, không bao giờ trên main.
• Chỉ viết spec cho công việc vượt qua ranh giới squad hoặc sẽ được đọc lại sau 90 ngày. Chạy theo spec-driven tốn khoảng gấp đôi thời gian và gấp ba token.

Các nguồn nói gì

Mặc định: ai cũng commit

Skill writing-plans của Superpowers lưu plan vào docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md, kèm một dòng bên dưới nói rằng tùy chọn về vị trí plan của người dùng sẽ ghi đè mặc định này s1. Skill brainstorming ghi bản thiết kế đã được duyệt vào docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md và kết thúc bằng "Commit the design document to git" s2. Spec Kit bố trí specs/[branch-name]/ gồm spec.md, plan.md và tasks.md, đánh số 001, 002, cùng một constitution trong memory/constitution.md s6. Kiro giữ .kiro/specs/ với mỗi tính năng một thư mục và mời các team "collaborate with team members on different features simultaneously" s8. Playbook của Anthropic nói rất rõ: "Every stage commits an artifact the next stage can read", "Commit the approved plan as plan.md", và "When implementation departs from the plan, update plan.md in the same commit" s5.

Không tài liệu nào trong số này nói ai sở hữu một spec đã commit hay khi nào nó hết đúng. Ba lỗi đã được ghi nhận nằm đúng trong khoảng trống đó.

Lỗi 1: rò rỉ ra công khai

Issue 1690, mở ngày 2026-06-05, báo rằng vị trí mặc định docs/superpowers/ có thể làm rò rỉ plan nội bộ vào tài liệu công khai qua Sphinx và Read the Docs s15. Dự án dính lỗi là okama, một thư viện Python với 273 sao. Commit sửa lỗi của họ thêm lại 5 plan và 3 spec, xóa một dòng .gitignore và ghi "track superpowers plans/specs in git, excluded from the Sphinx build" s21. Dòng 84 của docs/conf.py hiện có exclude_patterns = ["_build", "Thumbs.db", "superpowers"] s22. Hiện thư mục này chứa 8 plan và 6 spec s15. Team giữ nguyên thói quen và sửa lại build.

Lỗi 2: plan nằm trên main

Issue 1246, mở ngày 2026-04-22 và vẫn đang mở, hỏi vì sao plan được commit trước khi có development branch. Một người dùng báo "I'm getting 10 to 15 commits"; người khác: "Yes please, no plans and specs on main branch!" s16. Plugin không ép quy tắc về branch; checklist bên dưới thì có.

Lỗi 3: các override mà model bỏ qua

Issue 337 đóng ngày 2026-03-10 kèm ghi chú của maintainer rằng từ v5.0 plugin ưu tiên CLAUDE.md của dự án hơn mặc định của chính nó, dòng ví dụ: "Save plans to ~/.superpowers/plans/ instead of docs/plans/" s17. Issue 939, trên v5.0.6, cho thấy giới hạn: bảng "Output Paths" trong CLAUDE.md bị bỏ qua và spec vẫn rơi vào docs/superpowers/specs/. Cách xử lý hiệu quả là một dòng mệnh lệnh in đậm dưới bảng: design spec MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. Pull request 1020, vốn sắp xếp lại chỉ dẫn, bị đóng mà không merge s19. Override chỉ là một prompt, không phải một setting: hãy kiểm tra lại sau mỗi bản phát hành plugin. Với file nháp của chính plugin, issue 1780 được v6.0.3 đóng bằng thư mục .superpowers/sdd/ tự bỏ qua, tự tạo .gitignore chứa * s20.

Cá nhân và dùng chung

Claude Code ghi rõ cách tách này: "For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed" s3. Các file CLAUDE.md theo từng thư mục được nạp khi cần, "Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file", và setting claudeMdExcludes ẩn file của team khác trong monorepo s4. Git có ba lớp ignore, $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude và .gitignore s24; lớp giữa giấu thư mục plan cá nhân mà không đụng tới file dùng chung. CODEOWNERS lo nửa còn lại là quyền sở hữu: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23.

Vòng đời, như ADR

Bài viết năm 2011 của Michael Nygard là khuôn mẫu: một quyết định có thể "'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement", và "If a decision is reversed, we will keep the old one around, but mark it as superseded" s9. Thoughtworks chia cách dùng spec thành spec-first (viết một lần cho tác vụ), spec-anchored (giữ lại để phát triển tính năng) và spec-as-source (chỉ sửa spec), và tác giả thêm: "I'd rather review code than all these markdown files" s10. Superpowers ghi file kiểu spec-first rồi giữ mãi: mặc định là drift.

Drift và gate

Bài báo arXiv gọi tên vấn đề là "silent spec-code drift -- code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair" và đề xuất "a drift gate that makes spec-code divergence a blocking merge condition" s11. Hướng dẫn của chính Spec Kit cảnh báo: "Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7. TrueFoundry nói thẳng về lý do quản trị: "forty-one specs and nine agent files aren't a tidiness problem", đó là "forty-one unversioned behavior inputs and nine competing standing policies", và drift "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable". Bài đó cũng gợi ý khoảng 300 dòng mỗi spec và ngân sách 150 đến 200 chỉ dẫn thường trực s13. Một người dùng mô tả cách làm thủ công: "I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26.

Chi phí

Bake-off chỉ là một thử nghiệm và tác giả cũng nói vậy, nhưng chiều hướng nhất quán ở cả ba. Vì vậy: viết spec cho đường kiến trúc, giữ đường có giới hạn ở mức có giới hạn, và làm theo hai dòng mà những người dùng hay lặp lại, "don t spec too big / read the generated specs" s26.

Làm ngay thứ Hai

• Tạo docs/specs/<squad>/ cho mỗi squad và thêm một dòng CODEOWNERS cho mỗi thư mục, trỏ tới các reviewer của squad đó.
• Thêm một dòng mệnh lệnh in đậm vào CLAUDE.md của dự án: plan và spec MUST be saved under docs/specs/<squad>/, NOT docs/superpowers/. Chạy một brainstorm và kiểm tra file rơi vào đâu.
• Chuyển plan cá nhân sang một thư mục có trong .git/info/exclude và để các tùy chọn từng developer trong CLAUDE.local.md, bản thân nó cũng bị ignore.
• Đặt header trên mọi spec dùng chung: status (proposed, accepted, superseded), superseded-by, owner, paths, review-by.
• Viết drift gate: với mỗi spec có status: accepted, trích các path nó nhắc tới và làm pull request fail khi thiếu một path. Khoảng mười lăm dòng shell hoặc Python.
• Thêm quy tắc branch: không commit spec hay plan nào lên main ngoài pull request.
• Nếu repo xuất bản docs bằng Sphinx hoặc công cụ tương tự, thêm thư mục specs vào exclude_patterns ngay hôm nay.
• Đặt ngân sách kích thước: một spec giữ quanh 300 dòng, và chỉ công việc vượt ranh giới squad hoặc được đọc lại sau 90 ngày mới có spec.

Đọc thêm

• Đọc ba loại dùng spec (spec-first, spec-anchored, spec-as-source) trước khi chọn kiểu header; vòng đời chỉ có ý nghĩa với các file spec-anchored s10.
• Bài báo arXiv đi xa hơn kiểm tra path, tới một kiến trúc drift-enforced đầy đủ; hữu ích khi gate mười lăm dòng bắt đầu thấy quá thô s11.
• Hướng dẫn của Spec Kit nêu ba luồng tiến hóa (Flow-Forward, Living Spec, Flow-Back) khớp với quy tắc cùng commit s7.
• Playbook gợi ý một hook để ép plan và diff đồng bộ; thread Reddit về nó có 43 điểm và 27 bình luận với các báo cáo thực tế s5, s27.
• Lập luận của TrueFoundry rằng thay đổi spec là thay đổi policy, nên thuộc về sau một eval gate kèm metadata của lần chạy, là bước tiếp theo sau các kiểm tra path trong CI s13.
• Theo dõi hai issue còn mở, 1246 (plan trên main) và 939 (override bị bỏ qua); khi một trong hai đóng, một quy tắc trong pack này sẽ thành mặc định của plugin s16, s18.
• Bài viết đầy đủ của Marmelab giải thích vì sao 1,300 dòng xuất hiện và Spec Kit phát huy tác dụng ở đâu s14.

Nguồn

• Superpowers writing-plans skill, GitHub. Lý do nên đọc: đường dẫn mặc định chính xác và mệnh đề override một dòng mà bạn đang dựa vào.
• Superpowers brainstorming skill, GitHub. Lý do nên đọc: nơi spec được ghi và bước commit chúng.
• Claude Code memory, Anthropic. Lý do nên đọc: CLAUDE.local.md là chỗ chính thức cho tùy chọn cá nhân.
• Claude Code: working in large codebases, Anthropic. Lý do nên đọc: file theo thư mục, owner và claudeMdExcludes cho monorepo.
• The AI-native SDLC playbook, Anthropic. Lý do nên đọc: lập luận về audit trail và quy tắc cùng commit, từ chính nhà cung cấp.
• Spec Kit repository, GitHub. Lý do nên đọc: bố cục spec theo branch để so với bố cục theo squad.
• Spec Kit: evolving specs, GitHub. Lý do nên đọc: tuyên bố rõ nhất rằng spec và code không được mâu thuẫn.
• Kiro specs best practices, Kiro. Lý do nên đọc: bố cục thư mục theo tính năng dành cho các squad chạy song song.
• Documenting architecture decisions, Michael Nygard. Lý do nên đọc: bộ từ vựng status mà header mượn lại.
• Spec-driven development: the tools, Thoughtworks. Lý do nên đọc: sự phân biệt spec-first và spec-anchored quyết định nên giữ gì.
• The Spec Growth Engine, arXiv. Lý do nên đọc: lập luận chính thức cho một drift gate chặn merge.
• OpenSpec bake-off discussion, GitHub. Lý do nên đọc: số liệu chi phí song song duy nhất, kèm các lưu ý của chính tác giả.
• Spec-driven development for AI agents, TrueFoundry. Lý do nên đọc: spec như policy có version, và ngân sách 300 dòng.
• Spec-driven development: waterfall strikes back, Marmelab. Lý do nên đọc: 1,300 dòng spec cho một tính năng tầm thường trông như thế nào.
• Superpowers issue 1690, GitHub. Lý do nên đọc: báo cáo rò rỉ, từng bước một.
• Superpowers issue 1246, GitHub. Lý do nên đọc: phàn nàn về main branch, vẫn đang mở.
• Superpowers issue 337, GitHub. Lý do nên đọc: maintainer xác nhận CLAUDE.md thắng từ v5.0.
• Superpowers issue 939, GitHub. Lý do nên đọc: override đã thất bại và cách diễn đạt có tác dụng.
• Superpowers pull request 1020, GitHub. Lý do nên đọc: bản sửa đã thử, đóng mà không merge.
• Superpowers issue 1780, GitHub. Lý do nên đọc: cách plugin tự ignore thư mục nháp của mình.
• okama fix commit, GitHub. Lý do nên đọc: một team thật chọn giữ spec và loại chúng khỏi build.
• okama docs/conf.py, GitHub. Lý do nên đọc: dòng loại trừ Sphinx một dòng để chép.
• About code owners, GitHub Docs. Lý do nên đọc: cơ chế yêu cầu review mà quy tắc sở hữu dựa vào.
• gitignore documentation, Git. Lý do nên đọc: info/exclude là lớp ignore cá nhân mà nhiều developer quên.
• We tried spec-driven development for months, Reddit r/SpecDrivenDevelopment. Lý do nên đọc: báo cáo chi phí ở quy mô team, không có nhà cung cấp đứng sau.
• Does spec-driven development actually work for you?, Reddit r/ClaudeCode. Lý do nên đọc: lời khuyên về kích thước và đọc spec từ người dùng hằng ngày.
• Has anyone tried Anthropic's AI-native SDLC playbook?, Reddit r/ClaudeCode. Lý do nên đọc: báo cáo thực tế về playbook trong các repo thật.

FAQ

Có cần cả năm quy tắc ngay từ ngày đầu không?

Không. Việc đổi hướng trong CLAUDE.md và loại trừ Sphinx mất mười phút. Thêm CODEOWNERS và header khi một spec lần đầu vượt qua ranh giới squad, và thêm drift gate khi một spec đã accepted đã qua một sprint.

Drift gate bỏ sót điều gì?

Hành vi bị thay đổi. Nó chỉ kiểm tra path được nhắc tới còn tồn tại, nên một điều kiện bị đảo ngược vẫn qua. Hãy kết hợp với quy tắc cùng commit và review.

Sao không gitignore luôn thư mục đó?

Vì agent đọc spec sau này cần nó, và audit trail chỉ hoạt động nếu các mảnh ở giữa đều có version. Team okama đã thử gitignore rồi quay lại commit kèm loại trừ khỏi build.