最近這段時(shí)間，Harness這個(gè)詞突然火了起來(lái)，鋪天蓋地的營(yíng)銷文章讓人看得眼花繚亂，不少研發(fā)同學(xué)難免會(huì)慌：這又是什么新風(fēng)口，我是不是又落后了？其實(shí)大可不必焦慮，Harness從來(lái)不是什么憑空出現(xiàn)的“黑科技”，它更像是我們研發(fā)人早就一直在做的工程實(shí)踐，只是現(xiàn)在被正式定義、系統(tǒng)梳理，有了一個(gè)統(tǒng)一的名字而已。

很多人提到Harness，第一反應(yīng)就是“用AI多寫(xiě)點(diǎn)代碼”，但這其實(shí)是對(duì)它最大的誤解。真正的Harness，核心不是解放AI的生產(chǎn)力，而是把AI裝進(jìn)一套可控、可審計(jì)、可復(fù)用的工程流程里，讓AI從“一個(gè)不受控的高效助手”，變成“能穩(wěn)定融入生產(chǎn)研發(fā)的工程能力”。

對(duì)于我們?nèi)粘ｉ_(kāi)發(fā)的Java Spring Boot業(yè)務(wù)項(xiàng)目來(lái)說(shuō)，尤其是那些有一定歷史包袱、需求以增量改造為主的系統(tǒng)，最可怕的從來(lái)不是AI寫(xiě)不出代碼，而是AI在沒(méi)有邊界的情況下亂改代碼，不懂項(xiàng)目里的歷史隱性約定，把需求拆解、代碼實(shí)現(xiàn)、評(píng)審驗(yàn)證混為一談，改完代碼卻不明確風(fēng)險(xiǎn)，甚至觸碰SQL、配置這類高風(fēng)險(xiǎn)區(qū)域而沒(méi)有任何阻攔。

基于一次真實(shí)的Java Spring Boot項(xiàng)目實(shí)踐，我整理出了這套Harness最佳實(shí)踐，從核心原則、適用場(chǎng)景、倉(cāng)庫(kù)組織，到具體實(shí)踐、流程復(fù)盤、落地順序，全方位拆解如何把Harness思想落地到實(shí)際項(xiàng)目中。需要說(shuō)明的是，Harness思想本身和編程語(yǔ)言無(wú)關(guān)，弄懂了這套邏輯，不管是Python、Go還是其他語(yǔ)言，都能靈活復(fù)用。

一、先抓核心：Harness落地的4條關(guān)鍵原則

如果把Harness的所有實(shí)踐濃縮成最關(guān)鍵的幾條原則，我總結(jié)為4點(diǎn)，這也是我們整個(gè)項(xiàng)目落地的核心指導(dǎo)思想，記牢這4點(diǎn)，就不會(huì)偏離Harness的本質(zhì)。

第一，OpenSpec管變更生命周期。用/opsx:propose -> /opsx:apply -> /opsx:verify -> /opsx:archive這一套流程，管住“需求從提出到歸檔”的全過(guò)程，讓每一次變更都有跡可循、有章可依。

第二，AGENTS.md只當(dāng)?shù)貓D，不當(dāng)百科全書(shū)。AGENTS.md的核心作用是告訴AI“先看什么、按什么流程做”，相當(dāng)于一個(gè)入口導(dǎo)航；而真正的項(xiàng)目知識(shí)，比如架構(gòu)設(shè)計(jì)、業(yè)務(wù)規(guī)則、隱性約定，應(yīng)該統(tǒng)一放在docs/目錄下，避免AGENTS.md變得臃腫失控。

第三，Claude的硬約束靠permissions + hooks。把規(guī)則寫(xiě)在提示詞里，只是“軟約束”，AI難免會(huì)有判斷失誤的時(shí)候；真正能攔住危險(xiǎn)動(dòng)作的，是權(quán)限配置和鉤子函數(shù)，這才是Harness的“硬護(hù)欄”。

第四，團(tuán)隊(duì)專用動(dòng)作放到skills和subagents。比如代碼評(píng)審摘要生成、Spring分層架構(gòu)檢查、SQL風(fēng)險(xiǎn)審查這些高頻動(dòng)作，應(yīng)該沉淀成可重復(fù)調(diào)用的能力，而不是每次靠人臨時(shí)提醒AI，這樣才能提升流程的復(fù)用性和一致性。

如果再壓縮成一句話，就是：需求先工件化，知識(shí)先顯性化，執(zhí)行先加護(hù)欄，評(píng)審與驗(yàn)證必須分離。這十六個(gè)字，貫穿了我們整個(gè)Harness落地的全過(guò)程。

二、明確邊界：這套Harness方案適合哪些項(xiàng)目

不是所有項(xiàng)目都適合照搬這套Harness配置，它有自己的適用場(chǎng)景，找對(duì)場(chǎng)景才能發(fā)揮它的最大價(jià)值，避免畫(huà)蛇添足。

這套Harness最適合的，是這類Java Spring Boot項(xiàng)目：有一定的歷史包袱，不是全新的從0到1項(xiàng)目；需求以增量改造為主，比如迭代新功能、修復(fù)老bug、優(yōu)化現(xiàn)有邏輯，而不是整體重寫(xiě)；前后端之間存在一些口頭約定或隱性契約，這些約定沒(méi)有寫(xiě)進(jìn)文檔，新人或AI很難快速掌握；團(tuán)隊(duì)希望把AI編碼變成團(tuán)隊(duì)的“流程能力”，而不是某個(gè)人的個(gè)人技巧；需要把“需求、實(shí)現(xiàn)、評(píng)審、校驗(yàn)”這幾個(gè)環(huán)節(jié)明確拆開(kāi)，避免混在一起導(dǎo)致風(fēng)險(xiǎn)失控。

反之，如果你的項(xiàng)目是一個(gè)很小的demo倉(cāng)庫(kù)、一次性腳本倉(cāng)庫(kù)，或者是純實(shí)驗(yàn)性質(zhì)的項(xiàng)目，甚至是全新的從0到1項(xiàng)目，就沒(méi)必要照搬這套配置。這類項(xiàng)目更注重靈活性，約束太多反而會(huì)降低效率，可以考慮和Superpowers、ecc、omc等框架搭配使用，根據(jù)項(xiàng)目實(shí)際情況調(diào)整約束強(qiáng)度。

這里要強(qiáng)調(diào)一點(diǎn)，Harness的核心是“可控”，但不是“僵化”。我們的目標(biāo)是在約束和效率之間找到平衡，而不是為了約束而約束。

三、基礎(chǔ)鋪墊：適合Harness的倉(cāng)庫(kù)組織方式

要落地Harness，首先要搭建一個(gè)合理的倉(cāng)庫(kù)結(jié)構(gòu)，讓每個(gè)目錄、每個(gè)文件都有明確的職責(zé)，避免混亂。一個(gè)適合Java Spring Boot項(xiàng)目的Harness倉(cāng)庫(kù)結(jié)構(gòu)，建議如下（按目錄層級(jí)依次說(shuō)明，重點(diǎn)標(biāo)注核心文件和目錄的作用）：

repo/
├─ AGENTS.md                             # ?? 通用OpenSpec規(guī)則，AI的導(dǎo)航地圖
├─ CLAUDE.md                             # ?? Claude系統(tǒng)提示詞，定義AI的基礎(chǔ)行為
├─ REVIEW.md                             # ?? 只讀評(píng)審代理提示詞，規(guī)范評(píng)審標(biāo)準(zhǔn)
├─ docs/                                 # ?? 項(xiàng)目知識(shí)庫(kù)目錄，存放所有項(xiàng)目知識(shí)
│  ├─ architecture/                      # │  ├─ ?? 整體架構(gòu)知識(shí)
│  │  └─ index.md                        # │  │  └─ 項(xiàng)目架構(gòu)總覽，讓AI快速了解系統(tǒng)整體設(shè)計(jì)
│  │  └─ implicit-contracts.md           # │  │  └─ 隱性業(yè)務(wù)約定/項(xiàng)目坑點(diǎn)，核心中的核心
│  ├─ product/                           # │  ├─ ?? 產(chǎn)品知識(shí)
│  │  └─ index.md                        # │  │  └─ 產(chǎn)品規(guī)則，明確業(yè)務(wù)邏輯邊界
│  ├─ standards/                         # │  ├─ ?? 相關(guān)規(guī)范
│  │  ├─ testing.md                      # │  │  ├─ 測(cè)試規(guī)范，明確測(cè)試要求和標(biāo)準(zhǔn)
│  │  └─ database.md                     # │  │  └─ 數(shù)據(jù)庫(kù)與SQL規(guī)范，規(guī)避數(shù)據(jù)層風(fēng)險(xiǎn)
├─ openspec/                             # ?? OpenSpec執(zhí)行目錄，管理變更生命周期
│  ├─ changes/                           # │  ├─ 變更目錄，存放當(dāng)前和歷史變更
│  │  ├─ <changes名>                     # │  ├─ 當(dāng)前正在執(zhí)行的change，每個(gè)change對(duì)應(yīng)一個(gè)需求
│  │  │  ├─ specs/                       # │  │  │  ├─ 該change的工作原理說(shuō)明
│  │  │  ├─ proposal.md                  # │  │  │  ├─ 需求實(shí)現(xiàn)提案，拆解需求邊界
│  │  │  ├─ design.md                    # │  │  │  ├─ 具體執(zhí)行方案，明確技術(shù)實(shí)現(xiàn)細(xì)節(jié)
│  │  │  └─ task.md                      # │  │  │  └─ 執(zhí)行步驟節(jié)點(diǎn)，拆解具體工作內(nèi)容
│  │  └─ archive/                        # │  │  └─ 歸檔文件，存放已完成的change
│  └─ specs/                             # │  └─ 當(dāng)前系統(tǒng)工作原理說(shuō)明，讓AI了解系統(tǒng)現(xiàn)狀
├─ .claude/                              # ?? Claude項(xiàng)目級(jí)配置目錄，核心約束層
│  ├─ settings.local.json.example        # │  ├─ ?? 項(xiàng)目級(jí)權(quán)限設(shè)置，定義AI可操作范圍
│  ├─ skills/                            # │  ├─ ?? 項(xiàng)目級(jí)Skills，團(tuán)隊(duì)專用能力沉淀
│  │  ├─ prepare-review/                 # │  │  ├─ review前變更審計(jì)，生成評(píng)審摘要
│  │  │  └─ SKILL.md                     # │  │  │  └─ 該skill的具體執(zhí)行邏輯
│  │  ├─ spring-architecture-review/     # │  │  ├─ Springboot分層架構(gòu)檢查，避免分層混亂
│  │  │  └─ SKILL.md                     # │  │  │  └─ 架構(gòu)檢查的具體規(guī)則
│  │  └─ sql-risk-review/                # │  │  └─ SQL、Mapper、批量更新等風(fēng)險(xiǎn)檢查
│  │     └─ SKILL.md                     # │  │     └─ SQL風(fēng)險(xiǎn)檢查的具體規(guī)則
│  ├─ agents/                            # │  ├─ ?? 子代理，承擔(dān)專項(xiàng)審查職責(zé)
│  │  └─ reviewer.md                     # │  │  └─ 只讀評(píng)審代理，做獨(dú)立代碼審查
│  └─ hooks/                             # │  └─ ?? Hook，硬護(hù)欄的核心實(shí)現(xiàn)
│     ├─ guard_write.py                  # │     ├─ 文件寫(xiě)入保護(hù)，攔截高風(fēng)險(xiǎn)路徑寫(xiě)入
│     ├─ ensure_change_context.py        # │     ├─ 上下文變更保護(hù)，檢查change是否存在
│     └─ run_checks.sh                   # │     └─ 編譯檢查，自動(dòng)執(zhí)行編譯、測(cè)試等
├─ src/                                  # ?? 項(xiàng)目源代碼目錄，和常規(guī)Spring Boot項(xiàng)目一致
│  ├─ main/
│  │  ├─ java/
│  │  └─ resources/
│  └─ test/
│     ├─ java/
│     └─ resources/
├─ pom.xml                               # ?? Maven配置文件
└─ .gitignore                            # ?? Git忽略文件

這套結(jié)構(gòu)的核心不是“文件多”，而是“職責(zé)分層清晰”，每個(gè)目錄和文件都有明確的定位，不會(huì)出現(xiàn)職責(zé)交叉或遺漏。簡(jiǎn)單來(lái)說(shuō)，各核心目錄的職責(zé)可以總結(jié)為：

openspec/：管理“這次改什么”，負(fù)責(zé)把需求變成change工件，驅(qū)動(dòng)變更生命周期；

docs/：管理“這個(gè)項(xiàng)目本來(lái)是怎么工作的”，存放所有項(xiàng)目知識(shí)、規(guī)則和隱性約定；

AGENTS.md / CLAUDE.md / REVIEW.md：管理“AI進(jìn)入倉(cāng)庫(kù)后應(yīng)該怎么做”，是AI的基礎(chǔ)行為規(guī)范；

.claude/settings.json + hooks：管理“哪些事不能做、哪些檢查必須跑”，是Harness的硬護(hù)欄；

skills / agents：管理“團(tuán)隊(duì)專用的審查動(dòng)作”，沉淀可復(fù)用的團(tuán)隊(duì)經(jīng)驗(yàn)和能力。

搭建好這個(gè)倉(cāng)庫(kù)結(jié)構(gòu)，就為Harness的落地做好了基礎(chǔ)鋪墊，后續(xù)的所有實(shí)踐都將圍繞這個(gè)結(jié)構(gòu)展開(kāi)。

四、核心實(shí)踐：7個(gè)關(guān)鍵落地技巧（附實(shí)戰(zhàn)細(xì)節(jié)）

倉(cāng)庫(kù)結(jié)構(gòu)搭好之后，就進(jìn)入了核心實(shí)踐環(huán)節(jié)。這7個(gè)最佳實(shí)踐，是我們從真實(shí)項(xiàng)目中總結(jié)出來(lái)的經(jīng)驗(yàn)，每一個(gè)都解決了實(shí)際落地中的痛點(diǎn)，也是確保Harness能穩(wěn)定發(fā)揮作用的關(guān)鍵。

實(shí)踐一：AGENTS.md只做導(dǎo)航，不做知識(shí)庫(kù)

這是整個(gè)Harness落地過(guò)程中最容易踩坑的一點(diǎn)，很多團(tuán)隊(duì)一開(kāi)始會(huì)本能地把所有規(guī)則、知識(shí)都塞進(jìn)AGENTS.md，覺(jué)得這樣AI能一次性看到所有內(nèi)容，效率更高。但實(shí)際上，這樣做很快就會(huì)導(dǎo)致AGENTS.md臃腫不堪，后續(xù)維護(hù)困難，而且AI在讀取時(shí)也會(huì)抓不住重點(diǎn)，反而降低效率。

正確的做法是：AGENTS.md只負(fù)責(zé)告訴AI“去哪里看、按什么流程做”，相當(dāng)于一個(gè)入口導(dǎo)航，而真正的知識(shí)、規(guī)則、隱性約定，全部放進(jìn)docs/目錄下對(duì)應(yīng)的文件中。

具體來(lái)說(shuō)，AGENTS.md至少應(yīng)該包含這幾部分內(nèi)容：倉(cāng)庫(kù)采用的工作流是什么，AI進(jìn)入倉(cāng)庫(kù)后必須先讀哪些文件，沒(méi)有change是否允許開(kāi)始開(kāi)發(fā)，哪些目錄是受保護(hù)的，主要的命令入口是什么（比如/opsx:propose、/opsx:apply等）。

這里有一個(gè)判斷標(biāo)準(zhǔn)：如果你的AGENTS.md變得越來(lái)越長(zhǎng)，通常不是因?yàn)橐?guī)則變多了，而是因?yàn)槟銢](méi)有把知識(shí)正確拆分到docs目錄下。這時(shí)候就需要及時(shí)整理，把屬于項(xiàng)目知識(shí)的內(nèi)容遷移到docs/，讓AGENTS.md始終保持簡(jiǎn)潔，只做導(dǎo)航作用。

實(shí)踐二：把“隱性約定”單獨(dú)文檔化，避免踩坑

對(duì)于有歷史包袱的Java Spring Boot項(xiàng)目來(lái)說(shuō)，最危險(xiǎn)的往往不是那些寫(xiě)在文檔里的顯式規(guī)則，而是那些“大家都知道，但沒(méi)人寫(xiě)下來(lái)”的隱性約定。比如在我們這次實(shí)踐中，就遇到了兩個(gè)典型的隱性約定：status = null 和 status = 0 在歷史語(yǔ)義上并不等價(jià)，前端在單元詳情接口中，依賴contentResponse字段做回顯。

這些隱性約定如果只存在于口頭溝通中，AI基本不可能穩(wěn)定推斷出來(lái)，很容易在編碼時(shí)出錯(cuò)，導(dǎo)致“本地能跑、聯(lián)調(diào)出錯(cuò)”的問(wèn)題。所以，最佳實(shí)踐是：把所有容易導(dǎo)致聯(lián)調(diào)失敗的口頭約定，單獨(dú)沉淀到docs/architecture/implicit-contracts.md文件中。

而且要做到兩件事：一是在OpenSpec的design.md階段，就顯式檢查這些隱性約定，確保設(shè)計(jì)方案符合約定；二是在reviewer和verify階段，把這些約定作為對(duì)齊依據(jù)，避免實(shí)現(xiàn)時(shí)偏離約定。

這一步做得好不好，幾乎直接決定了AI產(chǎn)出代碼的可落地程度。很多團(tuán)隊(duì)用AI編碼時(shí)經(jīng)常出現(xiàn)“代碼能跑但不符合業(yè)務(wù)邏輯”的問(wèn)題，核心原因就是沒(méi)有把隱性約定顯性化，AI不懂項(xiàng)目的歷史包袱和業(yè)務(wù)潛規(guī)則。

實(shí)踐三：OpenSpec只管“變更生命周期”，不代替全部治理

很多人對(duì)OpenSpec的定位有誤解，覺(jué)得它可以包攬所有的項(xiàng)目治理工作，但實(shí)際上，OpenSpec的定位非常明確：它只負(fù)責(zé)把需求變成change工件，并驅(qū)動(dòng)change的生命周期，不負(fù)責(zé)代替其他的治理工作。

在Java Spring Boot項(xiàng)目中，我們推薦使用下面這條主流程來(lái)管理change的生命周期：/opsx:propose -> /opsx:apply -> /opsx:verify -> /opsx:archive。這四個(gè)步驟的職責(zé)的必須嚴(yán)格區(qū)分，不能混為一談。

第一步，/opsx:propose：把需求拆成一個(gè)change，產(chǎn)出proposal.md、design.md、tasks.md三個(gè)核心文件。這里有一個(gè)非常重要的實(shí)戰(zhàn)經(jīng)驗(yàn)：第一版proposal往往不靠譜，不要急著執(zhí)行。它更像第一輪工作草案，而不是最終方案。如果proposal拆錯(cuò)了，寧可廢棄當(dāng)前change，重新生成新的change，也不要硬著頭皮繼續(xù)做，否則后續(xù)會(huì)出現(xiàn)更多問(wèn)題，返工成本更高。

第二步，/opsx:apply：根據(jù)已經(jīng)確認(rèn)過(guò)的design.md和tasks.md實(shí)施代碼改動(dòng)。這一步的重點(diǎn)不是“讓AI盡量多寫(xiě)代碼”，而是“只做tasks.md范圍內(nèi)的事”，不允許AI自行擴(kuò)展需求，每完成一個(gè)里程碑，就自動(dòng)跑一次檢查，確保代碼沒(méi)有偏離設(shè)計(jì)方案。

第三步，/opsx:verify：核對(duì)“實(shí)現(xiàn)有沒(méi)有和OpenSpec工件對(duì)上”。這里要特別注意，verify的作用非常重要，但也非常有限：它不是代碼評(píng)審，也不是架構(gòu)評(píng)審，只負(fù)責(zé)檢查實(shí)現(xiàn)與change工件（proposal.md、design.md、tasks.md）是否一致，不負(fù)責(zé)檢查代碼質(zhì)量、架構(gòu)合理性等內(nèi)容。

第四步，/opsx:archive：把當(dāng)前change歸檔，保持openspec/changes/目錄下的進(jìn)行中上下文干凈，方便后續(xù)進(jìn)入下一個(gè)change。很多團(tuán)隊(duì)會(huì)忽略這一步，導(dǎo)致openspec/changes/目錄下堆滿了已完成的change，后續(xù)查找和管理非常麻煩。

實(shí)踐四：把“實(shí)現(xiàn)、評(píng)審、驗(yàn)證”徹底拆開(kāi)，各司其職

這是Harness和普通AI編碼方式最大的區(qū)別之一，也是確保AI編碼可控的核心。在真實(shí)的項(xiàng)目開(kāi)發(fā)中，下面這幾件事絕對(duì)不能混在一起：需求拆解、代碼實(shí)現(xiàn)、OpenSpec對(duì)齊校驗(yàn)、架構(gòu)審查、SQL風(fēng)險(xiǎn)審查、面向PR的人工閱讀摘要。

最佳實(shí)踐是把它們拆成不同的職責(zé)，讓每個(gè)環(huán)節(jié)只專注于自己的核心任務(wù)：

• /opsx:verify：只負(fù)責(zé)檢查“實(shí)現(xiàn)有沒(méi)有和OpenSpec對(duì)上”，確保代碼實(shí)現(xiàn)沒(méi)有偏離需求拆解和設(shè)計(jì)方案；
• /prepare-review：只負(fù)責(zé)整理“這次到底改了什么”，生成PR前的評(píng)審摘要，方便人工快速了解變更內(nèi)容，提高評(píng)審效率；
• /spring-architecture-review：只負(fù)責(zé)檢查Spring分層架構(gòu)有沒(méi)有亂，比如Controller里寫(xiě)業(yè)務(wù)邏輯、Service職責(zé)混亂等問(wèn)題；
• /sql-risk-review：只負(fù)責(zé)檢查SQL、Mapper、批量更新、索引和掃描范圍等數(shù)據(jù)層風(fēng)險(xiǎn)，比如批量更新沒(méi)有where限制、索引缺失等問(wèn)題；
• reviewer子代理：只負(fù)責(zé)做一輪獨(dú)立、只讀、偏代碼審查視角的檢查，重點(diǎn)關(guān)注代碼質(zhì)量、邏輯合理性等。

這樣拆開(kāi)的好處有兩個(gè)：一是每種審查都有明確的目標(biāo)，不會(huì)互相覆蓋又互相遺漏，比如不會(huì)出現(xiàn)“檢查了架構(gòu)卻忽略了SQL風(fēng)險(xiǎn)”的情況；二是出問(wèn)題時(shí)更容易定位，到底是proposal有問(wèn)題、實(shí)現(xiàn)有問(wèn)題，還是架構(gòu)/SQL有風(fēng)險(xiǎn)，不用在一堆混亂的流程中找原因。

實(shí)踐五：真正的硬護(hù)欄，必須落在permissions + hooks

很多團(tuán)隊(duì)喜歡把規(guī)則寫(xiě)進(jìn)提示詞，然后默認(rèn)AI會(huì)嚴(yán)格遵守，但在實(shí)際工程實(shí)踐中，這種做法并不可靠。AI難免會(huì)有判斷失誤的時(shí)候，一旦提示詞中的規(guī)則沒(méi)有被遵守，就可能觸碰高風(fēng)險(xiǎn)區(qū)域，導(dǎo)致線上事故。

最佳實(shí)踐是：能通過(guò)權(quán)限系統(tǒng)和hook強(qiáng)制攔住的，就不要只靠提示詞約束。提示詞是“軟約束”，權(quán)限和hook才是“硬護(hù)欄”，兩者結(jié)合才能確保風(fēng)險(xiǎn)可控。

比如下面這些目錄，在Java Spring Boot項(xiàng)目中屬于高風(fēng)險(xiǎn)區(qū)域，一旦被誤改，很可能導(dǎo)致線上故障：

src/main/resources/application*.yml、src/main/resources/bootstrap*.yml（配置文件，直接影響系統(tǒng)運(yùn)行）；

src/main/resources/db/、sql/（數(shù)據(jù)庫(kù)腳本，誤改可能導(dǎo)致數(shù)據(jù)丟失或錯(cuò)亂）；

deploy/、infra/（部署相關(guān)文件，誤改可能導(dǎo)致部署失?。?/p>

secrets/（密鑰文件，泄露會(huì)導(dǎo)致安全風(fēng)險(xiǎn)）。

對(duì)于這些路徑，我們建議直接在permissions.deny中禁止修改，同時(shí)在guard_write.py里再做一層路徑校驗(yàn)，雙重防護(hù)，確保即使AI判斷失誤，也無(wú)法修改這些高風(fēng)險(xiǎn)目錄下的文件。

同理，對(duì)于Bash執(zhí)行命令，也應(yīng)該分層控制。像mvn test、mvn -q -DskipTests compile、mvn -DskipTests package、git status、git diff這類安全命令，可以放入permissions.allow中，允許AI執(zhí)行；但像git push、kubectl、terraform、helm、rm -rf以及任何生產(chǎn)部署相關(guān)的命令，都應(yīng)該默認(rèn)禁止，避免AI誤操作導(dǎo)致嚴(yán)重后果。

實(shí)踐六：Hooks不只做攔截，還要做自動(dòng)檢查

在Claude Code場(chǎng)景下，hooks最有價(jià)值的地方，不只是阻止危險(xiǎn)動(dòng)作，還包括自動(dòng)補(bǔ)上執(zhí)行后校驗(yàn)，讓“檢查會(huì)不會(huì)跑”不再依賴模型自覺(jué)，而變成流程自動(dòng)發(fā)生，減少人工干預(yù)。

我們?cè)趯?shí)踐中，給hooks配置了三個(gè)核心功能，覆蓋了“寫(xiě)入前、命令前、寫(xiě)入后”三個(gè)關(guān)鍵節(jié)點(diǎn)：

• 寫(xiě)入前校驗(yàn)：通過(guò)guard_write.py攔截受保護(hù)路徑寫(xiě)入，一旦AI試圖修改高風(fēng)險(xiǎn)目錄下的文件，直接攔截并提示，不允許繼續(xù)操作；
• 命令前檢查上下文：通過(guò)ensure_change_context.py檢查當(dāng)前是否存在OpenSpec change，如果沒(méi)有change，對(duì)高風(fēng)險(xiǎn)Bash動(dòng)作直接提示確認(rèn)，而不是默認(rèn)放行，避免AI在沒(méi)有需求拆解的情況下亂執(zhí)行命令；
• 寫(xiě)入后自動(dòng)跑檢查：通過(guò)run_checks.sh在代碼變更后自動(dòng)執(zhí)行編譯檢查、單元測(cè)試、打包檢查，確保代碼能正常編譯、測(cè)試通過(guò)，避免出現(xiàn)“代碼能寫(xiě)但無(wú)法運(yùn)行”的問(wèn)題。同時(shí)，對(duì)于文檔類變更（比如修改docs/目錄下的文件），可以跳過(guò)重檢查，避免無(wú)謂的資源消耗。

這套設(shè)計(jì)的關(guān)鍵點(diǎn)是：把“被動(dòng)檢查”變成“主動(dòng)觸發(fā)”，不管AI有沒(méi)有意識(shí)到需要檢查，流程都會(huì)自動(dòng)執(zhí)行，確保每一次變更都經(jīng)過(guò)必要的校驗(yàn)，降低風(fēng)險(xiǎn)。

實(shí)踐七：Skill和Subagent只做團(tuán)隊(duì)專用能力

很多團(tuán)隊(duì)會(huì)把所有能力都硬塞進(jìn)主提示詞里，導(dǎo)致主提示詞越來(lái)越長(zhǎng)，維護(hù)困難，而且不同團(tuán)隊(duì)的需求不一樣，很多能力并不通用，強(qiáng)行塞進(jìn)主提示詞會(huì)造成冗余。

最佳實(shí)踐是：把團(tuán)隊(duì)專用的能力，沉淀到.claude/skills/和.claude/agents/目錄下，比如生成PR前的review摘要、檢查Spring Boot分層架構(gòu)、檢查SQL風(fēng)險(xiǎn)、做一輪只讀視角的reviewer審計(jì)等，這些能力都是團(tuán)隊(duì)在日常開(kāi)發(fā)中高頻使用的，而且具有團(tuán)隊(duì)特殊性，適合單獨(dú)沉淀。

這樣做有三個(gè)好處：一是可復(fù)用，以后每個(gè)change都可以重復(fù)調(diào)用這些能力，不用每次都重新寫(xiě)提示詞；二是可組合，不同類型的需求可以只調(diào)用需要的能力，比如不需要SQL變更的需求，就可以不調(diào)用sql-risk-review這個(gè)skill，提高效率；三是可演進(jìn)，團(tuán)隊(duì)后續(xù)可以持續(xù)補(bǔ)充自己的審查能力，比如新增“接口參數(shù)校驗(yàn)”“異常處理規(guī)范檢查”等skill，而不必頻繁修改系統(tǒng)提示詞，降低維護(hù)成本。

簡(jiǎn)單來(lái)說(shuō)，主流程負(fù)責(zé)通用約束，skills/agents負(fù)責(zé)團(tuán)隊(duì)私有經(jīng)驗(yàn)，兩者分工明確，才能讓Harness既規(guī)范又靈活。

五、標(biāo)準(zhǔn)工作流：從初始化到歸檔的完整流程

結(jié)合我們的實(shí)戰(zhàn)經(jīng)驗(yàn)，整理出了一套適合Java Spring Boot項(xiàng)目的Harness標(biāo)準(zhǔn)工作流，共7個(gè)步驟，從倉(cāng)庫(kù)初始化到change歸檔，形成完整閉環(huán)，團(tuán)隊(duì)可以直接復(fù)用，也可以根據(jù)自身項(xiàng)目情況微調(diào)。

第0步：初始化倉(cāng)庫(kù)（基礎(chǔ)準(zhǔn)備）

先通過(guò)openspec init --tools claude生成OpenSpec對(duì)應(yīng)的基礎(chǔ)目錄結(jié)構(gòu)，然后再補(bǔ)齊以下核心文件和目錄，確保倉(cāng)庫(kù)結(jié)構(gòu)符合Harness的要求：AGENTS.md、CLAUDE.md、REVIEW.md、docs/目錄（重點(diǎn)補(bǔ)齊implicit-contracts.md）、.claude/settings.json、.claude/hooks/、.claude/skills/、.claude/agents/。

這一階段的目標(biāo)不是“立刻開(kāi)始寫(xiě)代碼”，而是先把change生命周期、項(xiàng)目知識(shí)入口、權(quán)限和hook的承載位置搭好。如果這個(gè)骨架沒(méi)立起來(lái)，后面的流程就很容易重新滑回“想到哪改到哪”的無(wú)序狀態(tài)。

第1步：創(chuàng)建change（需求工件化）

執(zhí)行/opsx:propose命令，讓需求先變成change工件，生成proposal.md、design.md、tasks.md三個(gè)核心文件。這一步的核心是“需求拆解”，把模糊的需求變成清晰、可執(zhí)行的方案，避免后續(xù)開(kāi)發(fā)偏離需求。

第2步：人工審proposal/design/tasks（關(guān)鍵把關(guān)）

這一步絕對(duì)不能省，是控制風(fēng)險(xiǎn)的關(guān)鍵。人工重點(diǎn)檢查三個(gè)方面：一是需求邊界是不是對(duì)的，有沒(méi)有遺漏或多余的內(nèi)容；二是是否遺漏了項(xiàng)目中的隱性約定，確保設(shè)計(jì)方案符合項(xiàng)目歷史包袱；三是是否把多個(gè)問(wèn)題錯(cuò)誤混成一個(gè)change，避免change過(guò)大、邊界不清；四是tasks.md是否足夠可執(zhí)行，每個(gè)任務(wù)節(jié)點(diǎn)都要明確、具體，讓AI知道該做什么。

第3步：必要時(shí)廢棄change重來(lái)（及時(shí)止損）

如果proposal拆錯(cuò)了，或者design方案不符合需求，不要勉強(qiáng)修補(bǔ)。直接廢棄當(dāng)前change，重新生成新的change，往往更省成本。我們?cè)趯?shí)戰(zhàn)中就遇到過(guò)多次第一版proposal不符合需求的情況，及時(shí)廢棄重來(lái)，避免了后續(xù)更大的返工。

第4步：執(zhí)行/opsx:apply（代碼落地）

基于已確認(rèn)的proposal.md、design.md和tasks.md，執(zhí)行/opsx:apply命令，讓AI實(shí)施代碼變更。這一步要注意，AI只能做tasks.md范圍內(nèi)的事，不允許自行擴(kuò)展需求，每完成一個(gè)任務(wù)節(jié)點(diǎn)，就自動(dòng)跑一次檢查，確保代碼符合設(shè)計(jì)方案。

第5步：跑專項(xiàng)審查（風(fēng)險(xiǎn)排查）

代碼落地后，依次執(zhí)行專項(xiàng)審查，不建議一次性打包調(diào)用，分開(kāi)執(zhí)行更清晰、更可控：

• /prepare-review：生成PR前的評(píng)審摘要，整理本次變更的核心內(nèi)容，方便人工評(píng)審；
• /spring-architecture-review：進(jìn)行Spring分層架構(gòu)審計(jì)，檢查分層是否混亂，比如Controller寫(xiě)業(yè)務(wù)邏輯、Service職責(zé)過(guò)重等問(wèn)題；
• /sql-risk-review：進(jìn)行數(shù)據(jù)層和SQL風(fēng)險(xiǎn)審計(jì)，檢查SQL語(yǔ)句是否有風(fēng)險(xiǎn)、Mapper配置是否合理、批量更新是否有where限制等；
• @"reviewer (agent)"：讓reviewer子代理做一輪獨(dú)立、只讀的代碼審查，重點(diǎn)關(guān)注代碼質(zhì)量、邏輯合理性等。

第6步：執(zhí)行/opsx:verify（對(duì)齊校驗(yàn)）

專項(xiàng)審查完成后，執(zhí)行/opsx:verify命令，確認(rèn)代碼實(shí)現(xiàn)是否和OpenSpec change工件（proposal.md、design.md、tasks.md）對(duì)齊，確保沒(méi)有偏離需求和設(shè)計(jì)方案。如果發(fā)現(xiàn)不一致，及時(shí)修改代碼，重新執(zhí)行verify，直到對(duì)齊為止。

第7步：歸檔（閉環(huán)收尾）

所有檢查都通過(guò)后，執(zhí)行/opsx:archive命令，對(duì)當(dāng)前change進(jìn)行歸檔，將其移動(dòng)到openspec/changes/archive/目錄下，保持進(jìn)行中change目錄的干凈。到了這一步，這個(gè)change才算從“提出需求”走到了“完成閉環(huán)”。

六、實(shí)戰(zhàn)復(fù)盤：一次真實(shí)change的完整執(zhí)行過(guò)程

前面講的都是方法論，下面把我們這次Harness落地中的真實(shí)執(zhí)行過(guò)程保留下來(lái)，方便大家更直觀地理解：一條change在項(xiàng)目里到底是怎么從初始化、拆解、修正、執(zhí)行、審查一路跑完的。這些細(xì)節(jié)比單純的方法論更有參考價(jià)值，因?yàn)樗茏屇憧吹綄?shí)際落地中會(huì)遇到的問(wèn)題和解決方式。

1. 初始化倉(cāng)庫(kù)：先搭骨架，再填內(nèi)容

首先通過(guò)openspec init --tools claude生成OpenSpec對(duì)應(yīng)的基礎(chǔ)目錄結(jié)構(gòu)，然后我們開(kāi)始補(bǔ)齊AGENTS.md、CLAUDE.md、REVIEW.md這三個(gè)核心文件，明確AI的導(dǎo)航規(guī)則和行為規(guī)范。接著，我們重點(diǎn)完善了docs/目錄，尤其是docs/architecture/implicit-contracts.md，把項(xiàng)目中所有的隱性約定都整理進(jìn)去，比如前面提到的status字段語(yǔ)義、前端依賴的contentResponse字段等。最后，我們配置了.claude/settings.json、hooks、skills和agents，搭建好硬護(hù)欄和團(tuán)隊(duì)專用能力。

這一階段我們花了大概1天時(shí)間，沒(méi)有急于寫(xiě)代碼，而是先把倉(cāng)庫(kù)骨架搭好。事實(shí)證明，這一步的投入是值得的，后續(xù)的所有流程都能順暢推進(jìn)，沒(méi)有出現(xiàn)因?yàn)榻Y(jié)構(gòu)混亂導(dǎo)致的效率低下問(wèn)題。

2. 第一輪propose：快速成形，及時(shí)推翻

需求進(jìn)入后，我們先執(zhí)行/opsx:propose，讓AI拆解對(duì)應(yīng)change。很快，proposal.md、design.md、tasks.md等相關(guān)文件就生成了，但我們仔細(xì)審查后發(fā)現(xiàn)，第一版拆解并不符合真實(shí)需求——AI誤解了部分業(yè)務(wù)邏輯，把兩個(gè)不同的需求混在了一個(gè)change里，而且沒(méi)有考慮到項(xiàng)目中的隱性約定。

這時(shí)候我們沒(méi)有勉強(qiáng)繼續(xù)，而是直接廢棄了這個(gè)change。這也是Harness很重要的一條經(jīng)驗(yàn)：proposal不是生成出來(lái)就要執(zhí)行，第一版不對(duì)，就應(yīng)該及時(shí)推翻，避免后續(xù)返工。

3. 第二輪propose：重新拆解，持續(xù)細(xì)化

第一版廢棄之后，我們重新執(zhí)行/opsx:propose，生成新的change。但第一次生成后仍然不滿足需求，AI還是沒(méi)有完全理解業(yè)務(wù)邊界。于是我們開(kāi)始持續(xù)補(bǔ)充上下文，把項(xiàng)目的業(yè)務(wù)邏輯、隱性約定、需求邊界一一告訴AI，讓它修正理解偏差。

隨后，AI生成了新的proposal.md，我們?cè)俅螌彶?，發(fā)現(xiàn)還是有部分細(xì)節(jié)遺漏，于是繼續(xù)補(bǔ)充業(yè)務(wù)信息，讓AI進(jìn)一步修正。這一階段反復(fù)調(diào)整了3次，才最終確定了符合需求的proposal。

這個(gè)過(guò)程非常能體現(xiàn)Harness的現(xiàn)實(shí)意義：AI可以很快把change搭出一個(gè)骨架，但proposal的質(zhì)量，高度依賴你有沒(méi)有把真實(shí)業(yè)務(wù)邊界和上下文交代清楚。AI不是萬(wàn)能的，它需要明確的指引，才能產(chǎn)出符合需求的方案。

4. 進(jìn)入design：自動(dòng)生成是起點(diǎn)，人審是關(guān)鍵

在確認(rèn)了proposal的邊界和邏輯之后，我們讓AI繼續(xù)生成design.md，明確具體的技術(shù)實(shí)現(xiàn)細(xì)節(jié)。design.md生成后，我們開(kāi)始人工審計(jì)，發(fā)現(xiàn)其中存在一些錯(cuò)誤和遺漏，比如部分SQL語(yǔ)句的邏輯不符合數(shù)據(jù)庫(kù)規(guī)范，Spring分層設(shè)計(jì)有問(wèn)題，沒(méi)有考慮到異常處理場(chǎng)景。

于是我們開(kāi)始修正design.md，補(bǔ)充異常處理邏輯，調(diào)整SQL語(yǔ)句，優(yōu)化Spring分層設(shè)計(jì)。這不是一次就結(jié)束的，而是多輪審計(jì)、持續(xù)修正，前后調(diào)整了2次，才最終確定了符合要求的design方案。

這里出現(xiàn)了一個(gè)非常典型的問(wèn)題：由于proposal中已經(jīng)把范圍限定在adunit/save、adunit/update兩個(gè)接口，AI始終無(wú)法穩(wěn)定判定到素材相關(guān)的邏輯，無(wú)論我們?cè)趺囱a(bǔ)充上下文，AI都容易偏離范圍。

最后的處理方式是：當(dāng)前change先只處理adunit/save、adunit/update范圍內(nèi)的邏輯，素材相關(guān)的邏輯后續(xù)再單獨(dú)開(kāi)一個(gè)change。這樣一來(lái)，change的邊界變得清晰，AI也能準(zhǔn)確理解需求，后續(xù)的執(zhí)行過(guò)程也順利了很多。

這一段過(guò)程，正好印證了一條非常重要的最佳實(shí)踐：當(dāng)模型始終無(wú)法穩(wěn)定理解某塊邏輯時(shí)，優(yōu)先懷疑的往往不是模型能力，而是change邊界定義得不夠清楚。這時(shí)候，拆分change比強(qiáng)行讓AI理解更高效。

5. verify、apply和專項(xiàng)審查：分開(kāi)執(zhí)行，各司其職

在任務(wù)邊界清晰、design方案確認(rèn)之后，我們先讓子代理@"reviewer (agent)"通過(guò)/opsx:verify做了一輪驗(yàn)證，確認(rèn)design方案符合OpenSpec約定，沒(méi)有偏離需求。隨后，我們正式執(zhí)行/opsx:apply，讓AI開(kāi)始落地代碼。

代碼落地之后，我們沒(méi)有把所有審查動(dòng)作一次性打包調(diào)用，而是依次跑專項(xiàng)審查：

首先執(zhí)行/prepare-review，生成PR前的評(píng)審摘要，整理出本次變更的核心內(nèi)容、修改的文件、新增的功能，方便后續(xù)人工評(píng)審；

然后執(zhí)行/spring-architecture-review，進(jìn)行Spring分層架構(gòu)審計(jì)，發(fā)現(xiàn)AI在Controller里寫(xiě)了少量業(yè)務(wù)邏輯，我們及時(shí)修正，把業(yè)務(wù)邏輯遷移到Service層；

接著執(zhí)行/sql-risk-review，進(jìn)行數(shù)據(jù)層和SQL風(fēng)險(xiǎn)審計(jì)，發(fā)現(xiàn)一個(gè)批量更新語(yǔ)句沒(méi)有where限制，這是典型的事故隱患，我們立即補(bǔ)充where條件，避免后續(xù)出現(xiàn)數(shù)據(jù)錯(cuò)亂問(wèn)題；

之后，讓@"reviewer (agent)"再做一輪只讀審計(jì)，重點(diǎn)檢查代碼質(zhì)量和邏輯合理性，發(fā)現(xiàn)部分異常處理不完整，我們補(bǔ)充了異常捕獲和返回邏輯；

最后，我們?cè)賵?zhí)行一次/opsx:verify，檢查代碼實(shí)現(xiàn)是否仍然和OpenSpec工件一致，確保所有修改都沒(méi)有偏離需求和設(shè)計(jì)方案。

這一步最值得強(qiáng)調(diào)的是：verify、review、架構(gòu)審查、SQL審查不是一回事，它們有各自的職責(zé)，分開(kāi)編排更清晰、更可控，也更方便定位到底是哪一個(gè)環(huán)節(jié)出了問(wèn)題。如果把所有動(dòng)作混在一起，一旦出現(xiàn)問(wèn)題，很難快速找到原因，會(huì)浪費(fèi)大量時(shí)間。

6. 最后歸檔：完成閉環(huán)

所有審查都通過(guò)，代碼也已經(jīng)提交測(cè)試，確認(rèn)沒(méi)有問(wèn)題后，我們執(zhí)行/opsx:archive命令，對(duì)當(dāng)前change進(jìn)行歸檔，將其移動(dòng)到openspec/changes/archive/目錄下。到這一步，這個(gè)change才算真正完成，從需求提出到代碼落地、審查歸檔，形成了完整的閉環(huán)。

7. 實(shí)戰(zhàn)過(guò)程的核心感悟

把這段過(guò)程保留下來(lái)，比只講方法論更有價(jià)值，因?yàn)樗庇^地說(shuō)明了幾件事：

第一，第一版proposal往往只是草案，不能盲目執(zhí)行，人工審查必不可少，而且要敢于廢棄錯(cuò)誤的change，及時(shí)止損；

第二，design階段的人審，通常比apply后返工便宜得多，在design階段發(fā)現(xiàn)并修正問(wèn)題，能節(jié)省大量的后續(xù)返工成本；

第三，/opsx:verify不是萬(wàn)能審查，它必須和review、架構(gòu)審查、SQL審查分開(kāi)，各司其職，才能全面覆蓋風(fēng)險(xiǎn)；

第四，當(dāng)某塊邏輯始終解釋不清時(shí)，寧可拆change，也不要把所有問(wèn)題硬塞進(jìn)一個(gè)change，清晰的邊界是高效執(zhí)行的前提。

換句話說(shuō)，Harness的價(jià)值不只是“讓AI參與開(kāi)發(fā)”，而是讓整個(gè)開(kāi)發(fā)過(guò)程變成可拆解、可回退、可審計(jì)、可復(fù)用、可沉淀的流程，這才是它能真正融入生產(chǎn)研發(fā)的核心原因。

七、重點(diǎn)關(guān)注：Java Spring Boot項(xiàng)目最值得加護(hù)欄的5個(gè)地方

并不是所有限制都無(wú)腦加越多越好，約束太多會(huì)降低效率，約束太少會(huì)增加風(fēng)險(xiǎn)。我們始終認(rèn)為，在限制中保持簡(jiǎn)潔，AI才能更好地工作。結(jié)合Java Spring Boot項(xiàng)目的特點(diǎn)，下面這些坑最值得優(yōu)先考慮加護(hù)欄，也是我們?cè)趯?shí)戰(zhàn)中遇到的高頻問(wèn)題。

1. Controller寫(xiě)業(yè)務(wù)邏輯

這是Java Spring Boot項(xiàng)目中最常見(jiàn)的“臟問(wèn)題”，很多開(kāi)發(fā)人員（包括AI）都會(huì)習(xí)慣性地在Controller里寫(xiě)業(yè)務(wù)邏輯，導(dǎo)致分層混亂、代碼復(fù)用性差、維護(hù)困難。所以，我們需要在CLAUDE.md、REVIEW.md、reviewer子代理、spring-architecture-review這個(gè)skill中同時(shí)卡住，明確規(guī)定Controller只能負(fù)責(zé)接收請(qǐng)求、返回響應(yīng)，不能包含任何業(yè)務(wù)邏輯，業(yè)務(wù)邏輯必須放在Service層。

2. 直接改SQL/配置/數(shù)據(jù)庫(kù)腳本

這類改動(dòng)往往“本地能跑，線上出事”，比如修改配置文件導(dǎo)致系統(tǒng)啟動(dòng)失敗，修改SQL腳本導(dǎo)致數(shù)據(jù)丟失，修改數(shù)據(jù)庫(kù)腳本導(dǎo)致表結(jié)構(gòu)異常。所以，我們應(yīng)該通過(guò)permissions.deny、guard_write.py、database.md、sql-risk-review這個(gè)skill多層保護(hù)，禁止AI直接修改這些高風(fēng)險(xiǎn)文件，如需修改，必須經(jīng)過(guò)人工審批，重新生成change，按流程執(zhí)行。

3. Service過(guò)胖，職責(zé)混亂

這類問(wèn)題很容易在AI連續(xù)補(bǔ)代碼時(shí)越滾越大，一個(gè)Service負(fù)責(zé)多個(gè)不相關(guān)的業(yè)務(wù)邏輯，導(dǎo)致代碼臃腫、邏輯混亂、難以維護(hù)。我們需要靠reviewer子代理和spring-architecture-review這個(gè)skill持續(xù)盯住，一旦發(fā)現(xiàn)Service職責(zé)混亂，及時(shí)拆分Service，明確每個(gè)Service的核心職責(zé)。

4. 測(cè)試只跑happy path

這是很多項(xiàng)目的通病，AI在寫(xiě)測(cè)試用例時(shí)，也容易只考慮正常場(chǎng)景，忽略異常場(chǎng)景、邊界場(chǎng)景，導(dǎo)致測(cè)試覆蓋率不足，潛在bug無(wú)法被發(fā)現(xiàn)。所以，我們至少要在testing.md和review摘要里明確：本次變更跑了哪些測(cè)試，哪些場(chǎng)景沒(méi)有測(cè)，為什么當(dāng)前可以接受，避免測(cè)試流于形式。

5. 批量更新沒(méi)有where限制

這類問(wèn)題不是bug，而是事故預(yù)告。一旦批量更新沒(méi)有where限制，會(huì)導(dǎo)致全表數(shù)據(jù)被修改，造成嚴(yán)重的數(shù)據(jù)錯(cuò)亂，甚至無(wú)法恢復(fù)。所以，在數(shù)據(jù)庫(kù)規(guī)范（database.md）和SQL風(fēng)險(xiǎn)審查（sql-risk-review）里，必須把它作為顯式檢查項(xiàng)，一旦發(fā)現(xiàn)，直接攔截，不允許執(zhí)行。

八、實(shí)戰(zhàn)補(bǔ)充：3條千金難買的落地經(jīng)驗(yàn)

除了前面講的結(jié)構(gòu)設(shè)計(jì)和最佳實(shí)踐，這次Harness落地還有3條很重要的經(jīng)驗(yàn)，這些經(jīng)驗(yàn)不是來(lái)自理論，而是來(lái)自實(shí)際操作中的踩坑和總結(jié)，對(duì)后續(xù)團(tuán)隊(duì)落地Harness非常有幫助。

1. 第一版proposal通常只是草案，人工審查不能省

AI很容易先產(chǎn)出一個(gè)“結(jié)構(gòu)看起來(lái)合理、業(yè)務(wù)邊界其實(shí)不對(duì)”的proposal，尤其是對(duì)于有歷史包袱、業(yè)務(wù)邏輯復(fù)雜的項(xiàng)目，AI很難一次性理解所有細(xì)節(jié)。因此，proposal階段的人工審查，絕對(duì)不能省，而且要仔細(xì)審查，重點(diǎn)關(guān)注需求邊界、隱性約定、change拆分是否合理，避免后續(xù)出現(xiàn)更大的問(wèn)題。

2. design階段修正，比apply后返工便宜得多

一旦進(jìn)入apply階段，錯(cuò)誤就開(kāi)始變成代碼、測(cè)試和聯(lián)調(diào)成本，此時(shí)再修正錯(cuò)誤，需要修改代碼、重新測(cè)試、重新聯(lián)調(diào)，耗時(shí)耗力。而在design階段，錯(cuò)誤還只是“方案上的問(wèn)題”，修正起來(lái)只需要調(diào)整設(shè)計(jì)方案，成本低、效率高。所以，最值得花時(shí)間的地方，其實(shí)是design階段，多花一點(diǎn)時(shí)間審查和修正design方案，能節(jié)省大量的后續(xù)返工成本。

3. change邊界不清時(shí)，寧可拆成多個(gè)change

如果模型始終無(wú)法穩(wěn)定理解某塊邏輯，通常不是因?yàn)樗?ldquo;再多想一輪就會(huì)懂”，而是因?yàn)楫?dāng)前change邊界定義得不夠好，包含了太多不相關(guān)的內(nèi)容，導(dǎo)致AI無(wú)法抓住重點(diǎn)。這時(shí)候，最佳實(shí)踐不是繼續(xù)硬壓AI理解，而是把復(fù)雜問(wèn)題拆開(kāi)，先讓change邊界變清晰，一個(gè)change只負(fù)責(zé)一個(gè)明確的需求，這樣AI能更準(zhǔn)確地理解需求，執(zhí)行效率也會(huì)更高。

九、團(tuán)隊(duì)落地：推薦的3階段實(shí)施順序

如果團(tuán)隊(duì)想逐步引入這套Harness，不建議一次性全部落地，那樣成本太高，也容易出現(xiàn)混亂。我們建議按下面3個(gè)階段落地，循序漸進(jìn)，逐步完善，讓團(tuán)隊(duì)有一個(gè)適應(yīng)的過(guò)程。

第一階段：最小可用版（1-2周）

先上最核心的幾個(gè)組件，把“變更工件化”和“隱性約定顯性化”跑通：

• OpenSpec：搭建openspec/目錄，使用/opsx:propose -> /opsx:apply -> /opsx:verify -> /opsx:archive流程管理change；
• AGENTS.md：編寫(xiě)AI導(dǎo)航地圖，明確AI的基礎(chǔ)流程和入口；
• CLAUDE.md：編寫(xiě)Claude系統(tǒng)提示詞，規(guī)范AI的基礎(chǔ)行為；
• docs/architecture/implicit-contracts.md：整理項(xiàng)目中的隱性約定，讓AI了解項(xiàng)目歷史包袱；
• reviewer子代理：實(shí)現(xiàn)基礎(chǔ)的只讀評(píng)審能力，輔助人工審查。

這個(gè)階段的目標(biāo)是：讓每一次需求變更都能變成change工件，有明確的拆解和記錄，AI能了解項(xiàng)目的隱性約定，避免出現(xiàn)“聯(lián)調(diào)出錯(cuò)”的問(wèn)題。

第二階段：補(bǔ)硬護(hù)欄（2-3周）

在第一階段的基礎(chǔ)上，增加硬護(hù)欄，讓高風(fēng)險(xiǎn)動(dòng)作可控：

• permissions：配置權(quán)限，禁止AI修改高風(fēng)險(xiǎn)目錄和文件；
• guard_write.py：實(shí)現(xiàn)文件寫(xiě)入保護(hù)，攔截高風(fēng)險(xiǎn)路徑寫(xiě)入；
• ensure_change_context.py：實(shí)現(xiàn)上下文變更保護(hù)，檢查change是否存在；
• 自動(dòng)檢查：配置run_checks.sh，實(shí)現(xiàn)代碼變更后自動(dòng)執(zhí)行編譯、測(cè)試、打包檢查。

這個(gè)階段的目標(biāo)是：通過(guò)權(quán)限和hook，強(qiáng)制攔住危險(xiǎn)動(dòng)作，讓AI的操作始終在安全范圍內(nèi)，減少人工干預(yù)的成本。

第三階段：補(bǔ)團(tuán)隊(duì)專用能力（持續(xù)迭代）

最后，補(bǔ)充團(tuán)隊(duì)專用的skills和agents，讓流程真正變成可復(fù)用的工程能力：

• prepare-review：實(shí)現(xiàn)PR前評(píng)審摘要生成能力；
• spring-architecture-review：實(shí)現(xiàn)Spring分層架構(gòu)檢查能力；
• sql-risk-review：實(shí)現(xiàn)SQL風(fēng)險(xiǎn)審查能力；
• 其他團(tuán)隊(duì)私有skills/agents：根據(jù)團(tuán)隊(duì)需求，新增接口參數(shù)校驗(yàn)、異常處理規(guī)范檢查等能力。

這個(gè)階段的目標(biāo)是：沉淀團(tuán)隊(duì)的私有經(jīng)驗(yàn)，讓Harness更貼合團(tuán)隊(duì)的實(shí)際需求，進(jìn)一步提高開(kāi)發(fā)效率和代碼質(zhì)量，減少人工審查的工作量。

十、附錄：可直接復(fù)用的Harness檢查清單

為了方便團(tuán)隊(duì)落地和自查，我們整理了一份可直接復(fù)用的檢查清單，涵蓋倉(cāng)庫(kù)層、流程層、風(fēng)險(xiǎn)層三個(gè)維度，對(duì)照這份清單，就能快速判斷你的Harness是否具備了在真實(shí)項(xiàng)目里穩(wěn)定運(yùn)行的基礎(chǔ)。

倉(cāng)庫(kù)層檢查清單

? 是否有AGENTS.md

? 是否有CLAUDE.md

? 是否有REVIEW.md

? 是否有docs/architecture/implicit-contracts.md

? 是否有openspec/changes/目錄

? 是否有.claude/settings.json

? 是否有hooks、skills、agents目錄

流程層檢查清單

? 沒(méi)有change時(shí)，不允許直接開(kāi)始開(kāi)發(fā)

? proposal/design/tasks是否經(jīng)人工審計(jì)

? apply后是否自動(dòng)跑檢查

? verify是否獨(dú)立執(zhí)行

? change完成后是否archive

風(fēng)險(xiǎn)層檢查清單

? 高風(fēng)險(xiǎn)目錄是否已deny

? SQL/Mapper是否有專項(xiàng)風(fēng)險(xiǎn)檢查

? 測(cè)試缺口是否被顯式說(shuō)明

? Spring分層是否有獨(dú)立審查

? 隱性約定是否在docs中顯性記錄

如果這些項(xiàng)大部分都能滿足，說(shuō)明你的Harness基本已經(jīng)具備了在真實(shí)項(xiàng)目里穩(wěn)定運(yùn)行的基礎(chǔ)。如果有遺漏，可以對(duì)照清單逐步完善。另外，我們這次實(shí)踐的相關(guān)配置文件也已經(jīng)打包好了，大家可以用于參考，公眾號(hào)后臺(tái)回復(fù)「20260401」即可獲取。

最后：別被新詞嚇到，Harness的本質(zhì)是工程實(shí)踐的沉淀

說(shuō)實(shí)話，最近Harness這個(gè)詞一出來(lái)，營(yíng)銷號(hào)鋪天蓋地的宣傳，導(dǎo)致很多人都會(huì)有點(diǎn)慌，覺(jué)得這又是一個(gè)新的風(fēng)口，自己如果不跟上，就會(huì)被淘汰。但其實(shí)，Harness真的沒(méi)那么嚇人。

因?yàn)槲覀円郧白鲰?xiàng)目的時(shí)候，也一直在做差不多的事。我們會(huì)定開(kāi)發(fā)規(guī)則，會(huì)加權(quán)限限制，會(huì)做代碼審查，會(huì)留回退方案；會(huì)告訴工具什么能做，什么不能做；什么可以自動(dòng)跑，什么一定要人來(lái)拍板。這些事，我們以前就在做，只是那時(shí)候沒(méi)有一個(gè)很統(tǒng)一的名字，把它們都組織到一起。

所以我想說(shuō)，別被新詞嚇到。Harness不是突然從天上掉下來(lái)的東西，它更像是我們?cè)缇投?、早就在做的一些工程?jīng)驗(yàn)，現(xiàn)在終于被定義出了名字，被系統(tǒng)梳理成了一套可復(fù)用的流程。

只是到了AI coding時(shí)代，這件事反而更重要了。因?yàn)锳I很像一個(gè)特別能干的小幫手，做事快，寫(xiě)東西也快，但它快不代表它每次都對(duì)，它能做很多事也不代表它知道哪條線不能碰。所以我們要給它規(guī)則，給它邊界，給它檢查，也給它剎車。這其實(shí)就是Harness思想最有價(jià)值的地方：不是讓AI隨便沖，而是讓它在可控的路上跑，讓AI真正成為提升團(tuán)隊(duì)效率的工具，而不是增加風(fēng)險(xiǎn)的隱患。

到此這篇關(guān)于Harness實(shí)戰(zhàn)指南之如何在Java Spring Boot項(xiàng)目中規(guī)范落地OpenSpec+Claude Code的文章就介紹到這了,更多相關(guān)java springboot項(xiàng)目落地OpenSpec+Claude Code內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論