1. 從“提交信息”到“知識協(xié)議”一個被忽視的工程實(shí)踐如果你和我一樣每天都要和 Git 打交道那么git commit -m “fix: update something”這樣的操作可能已經(jīng)成了肌肉記憶。我們習(xí)慣了把提交信息當(dāng)作一個簡單的、面向人類的“備忘錄”記錄一下這次改了啥方便以后回溯。但最近我在一個大型的、由多個 AI 編碼助手比如 GitHub Copilot、Cursor 等協(xié)作參與的項(xiàng)目里遇到了一個頭疼的問題這些 AI 助手之間以及它們與人類開發(fā)者之間對于代碼變更的“上下文”理解是割裂的。比如我讓 AI A 基于某個需求重構(gòu)了模塊 X提交信息是“重構(gòu)模塊 X 以支持動態(tài)配置”。幾天后另一位同事或者另一個 AI 助手 B需要修改模塊 X 的一個相關(guān)函數(shù)但它完全不知道這次重構(gòu)背后的“動態(tài)配置”具體指什么、邊界在哪里、有哪些已知的坑。它只能看到最終的代碼 diff卻丟失了那次變更的“意圖”和“上下文”。這直接導(dǎo)致了后續(xù)修改引入了回歸缺陷或者做出了與最初設(shè)計相悖的決策。這讓我開始重新審視 Git 提交信息。它難道只能是一段隨意的文本嗎在 AI 智能體逐漸成為開發(fā)流程中固定“成員”的今天我們能否重新定義它的角色這就是Lore這個想法誕生的背景。Lore 不是一個全新的工具而是一種設(shè)計理念和協(xié)議將 Git 提交信息重新定位為一種結(jié)構(gòu)化的知識交換協(xié)議專門服務(wù)于 AI 編碼助手之間的協(xié)作與知識傳承。簡單說Lore 主張我們像設(shè)計 API 接口一樣去設(shè)計我們的提交信息。讓它包含機(jī)器可讀的、結(jié)構(gòu)化的上下文而不僅僅是人類可讀的摘要。這樣任何一個接入此協(xié)議的 AI 助手在查看歷史提交時不僅能知道“代碼變了什么”還能理解“為什么變”、“變更的約束條件是什么”、“相關(guān)的決策上下文有哪些”。這相當(dāng)于為項(xiàng)目的 Git 歷史建立了一個持續(xù)增長的、結(jié)構(gòu)化的“項(xiàng)目記憶庫”任何新的 AI 智能體加入都能快速通過閱讀這個記憶庫來理解項(xiàng)目的設(shè)計脈絡(luò)和隱形規(guī)則而不是面對一堆冰冷的代碼變更記錄茫然無措。2. 為什么傳統(tǒng)的提交信息在 AI 協(xié)作時代“不夠用”了在純?nèi)祟悈f(xié)作的團(tuán)隊(duì)里提交信息即使寫得簡略問題也不大。因?yàn)槿祟愰_發(fā)者具備“隱性知識”和“情境理解”能力?？吹健靶迯?fù)了空指針異?！边@樣的提交同事能結(jié)合最近的討論、JIRA 票號、甚至私下的一句吐槽腦補(bǔ)出完整的上下文。但 AI 助手目前做不到這一點(diǎn)。它們本質(zhì)上是“上下文饑渴”的模型其理解完全依賴于我們喂給它們的提示詞Prompt和上下文窗口內(nèi)的內(nèi)容。傳統(tǒng)的、非結(jié)構(gòu)化的提交信息對它們來說信息密度太低噪聲太高。2.1 AI 編碼助手的協(xié)作瓶頸分析讓我們具體拆解一下當(dāng)多個 AI 助手或人與 AI 混合基于同一個 Git 倉庫工作時會面臨哪些傳統(tǒng)工作流無法解決的挑戰(zhàn)上下文丟失與知識斷層這是最核心的問題。AI 助手 A 完成一個任務(wù)時其思考過程、權(quán)衡的備選方案、排除某些路徑的原因這些寶貴的“決策邏輯”通常只存在于它單次會話的臨時上下文中。一旦會話結(jié)束這些知識就消失了。后續(xù)的 AI 助手 B 接手時面對的就是一個“黑盒”變更它無法獲知 A 當(dāng)時的約束條件比如“因?yàn)樾阅芸紤]所以沒有采用方案 Y”這極易導(dǎo)致決策沖突。意圖傳遞失真人類寫的提交信息如“優(yōu)化數(shù)據(jù)庫查詢”其“優(yōu)化”的標(biāo)準(zhǔn)是什么是降低了延遲還是減少了 IO抑或是簡化了查詢邏輯便于維護(hù)AI 在解讀時可能存在歧義。而如果提交信息能結(jié)構(gòu)化地包含“指標(biāo)將平均查詢耗時從 120ms 降低至 15ms”那么意圖就清晰無誤了。變更原因與影響鏈難以追溯一個修復(fù)了“內(nèi)存泄漏”的提交其根本原因可能是三天前另一個“引入緩存”的提交。在純代碼 Diff 中這種因果鏈?zhǔn)请[式的。結(jié)構(gòu)化的提交信息可以包含“根因提交哈?！薄ⅰ瓣P(guān)聯(lián)問題”等字段顯式地建立鏈接幫助 AI 理解缺陷的生命周期。規(guī)范與約束的滲透效率低團(tuán)隊(duì)的技術(shù)規(guī)范如“禁止使用某個已廢棄的 API”、“所有配置必須支持熱更新”通常寫在文檔里。AI 助手可能在編碼時被提醒但很難在審查歷史代碼或理解他人提交時主動關(guān)聯(lián)這些規(guī)范。結(jié)構(gòu)化的提交信息可以把“遵循的規(guī)范”或“做出的權(quán)衡”作為元數(shù)據(jù)嵌入讓規(guī)范隨著每一次提交被“固化”和“傳播”。2.2 現(xiàn)有方案的局限性面對這些問題社區(qū)并非沒有嘗試。比如更詳細(xì)的提交信息規(guī)范如 Conventional Commits它定義了feat、fix、BREAKING CHANGE等類型和格式是一個巨大進(jìn)步。但它主要服務(wù)于自動化生成 CHANGELOG 和版本號其結(jié)構(gòu)仍是面向發(fā)布流程的而非面向 AI 的深度上下文交換。在代碼注釋中詳細(xì)說明這當(dāng)然有幫助但注釋會隨著代碼重構(gòu)而失效或變得不相關(guān)且缺乏統(tǒng)一的解析方式。依賴外部系統(tǒng)如將完整的設(shè)計文檔鏈接到 JIRA 或 Confluence。但這要求 AI 助手具備跨工具檢索和理解的能力且鏈接可能失效形成了另一個信息孤島。Lore 的思路是“就地解決”利用 Git 這個所有開發(fā)者包括 AI都必須且已經(jīng)在使用的、最基礎(chǔ)的協(xié)作設(shè)施將其承載的信息“升級”使其原生具備服務(wù) AI 協(xié)作的能力。這有點(diǎn)像 HTTP 協(xié)議從 1.0 到 2.0 的演進(jìn)底層傳輸載體沒變但協(xié)議本身變得更高效、更能表達(dá)復(fù)雜意圖。3. Lore 協(xié)議設(shè)計定義 AI 可讀的“提交語義”Lore 的核心是一套輕量級的、可擴(kuò)展的結(jié)構(gòu)化數(shù)據(jù)協(xié)議。它不強(qiáng)制要求改變 Git 本身而是約定如何在現(xiàn)有的提交信息體中嵌入機(jī)器可讀的區(qū)塊。其設(shè)計原則是人類可讀優(yōu)先機(jī)器可讀次之增量采用向后兼容。3.1 基礎(chǔ)協(xié)議格式一個遵循 Lore 協(xié)議的提交信息可能長這樣feat(api): 為用戶服務(wù)添加分頁查詢接口 本次變更實(shí)現(xiàn)了 GET /users 端點(diǎn)的分頁功能以應(yīng)對用戶列表增長后的性能問題。 ## Lore-Context { “protocol_version”: “0.1.0”, “change_intent”: “performance_optimization”, “requirements”: [“PROJ-123”, “PROJ-456”], “constraints”: { “backward_compatibility”: “must”, “performance_target”: “p99 latency 200ms under 1000 RPS” }, “decisions”: [ { “problem”: “如何選擇分頁游標(biāo)編碼方式”, “options”: [“offset-limit”, “cursor-based (encrypted timestamp)”, “cursor-based (serialized ID)”], “chosen”: “cursor-based (encrypted timestamp)”, “reason”: “避免 offset-limit 在深度分頁時的性能劣化同時相比序列化 ID 方案更易于客戶端處理且無需暴露內(nèi)部 ID。” } ], “dependencies”: [“a1b2c3d”], “tests”: { “added”: [“test_user_pagination.py”], “updated”: [“test_user_api.py”] } } ## Lore-Context-End 具體的實(shí)現(xiàn)細(xì)節(jié)包括 - 新增 PaginatedResponse 模型。 - 在 UserService 中實(shí)現(xiàn) list_users 游標(biāo)邏輯。 - 更新了 API 文檔。可以看到它在常規(guī)的提交描述下方增加了一個## Lore-Context和## Lore-Context-End標(biāo)記的區(qū)塊。這個區(qū)塊內(nèi)部是一個 JSON 對象這就是 Lore 協(xié)議定義的結(jié)構(gòu)化知識。3.2 核心字段詳解與設(shè)計考量我們來拆解這個 JSON 里的關(guān)鍵字段以及為什么它們對 AI 助手至關(guān)重要protocol_version: 標(biāo)識所用 Lore 協(xié)議的版本。這允許協(xié)議本身向前演進(jìn)AI 助手可以據(jù)此調(diào)整解析邏輯。change_intent: 變更的核心意圖分類。比 Conventional Commits 的type更細(xì)致。例如performance_optimization(性能優(yōu)化)bug_fix(缺陷修復(fù))refactor(重構(gòu))security_patch(安全補(bǔ)丁)dependency_update(依賴更新)feature_implementation(功能實(shí)現(xiàn))這個字段能快速幫助 AI 對變更進(jìn)行高層級分類優(yōu)先關(guān)注某些類型的變更如安全補(bǔ)丁。requirements: 關(guān)聯(lián)的需求或任務(wù) ID如 JIRA KEY。這提供了變更的業(yè)務(wù)上下文源頭。constraints: 本次變更必須遵守的約束條件。這是防止后續(xù) AI 引入回歸的關(guān)鍵。例如backward_compatibility:“must”/“optional”/“breaking”。明確告知后續(xù)修改者是否必須保持 API 兼容。performance_target: 具體的性能指標(biāo)。后續(xù) AI 在修改相關(guān)代碼時必須運(yùn)行性能測試來驗(yàn)證是否仍滿足此目標(biāo)。third_party_contract: 如果變更涉及外部系統(tǒng)接口可以在此說明契約。decisions:這是 Lore 協(xié)議的靈魂所在。它記錄開發(fā)過程中面臨的關(guān)鍵決策點(diǎn)。每個決策包含problem: 遇到的問題。options: 考慮過的備選方案。chosen: 最終選擇的方案。reason: 選擇該方案的理由技術(shù)權(quán)衡、業(yè)務(wù)考量等。這個字段將“為什么這么做”的隱性知識顯式化。當(dāng) AI 在未來看到這段代碼產(chǎn)生疑惑時可以直接從這里找到設(shè)計 rationale避免重新討論或做出矛盾決策。dependencies: 此變更所依賴的前序提交哈希列表。顯式聲明依賴關(guān)系可以幫助 AI 理解變更的先后順序和邏輯基礎(chǔ)在git bisect或排查問題時也能快速定位關(guān)聯(lián)變更集。tests: 指明新增或更新的測試文件。這引導(dǎo) AI 在修改相關(guān)功能時知道應(yīng)該去哪些測試文件中尋找測試用例并提醒它可能需要更新這些測試。注意Lore 協(xié)議定義的字段是建議性的團(tuán)隊(duì)可以根據(jù)自身需要擴(kuò)展。例如可以添加“known_issues”字段來記錄本次引入但尚未解決的次要問題或者“rollback_procedure”字段記錄回滾步驟。關(guān)鍵在于團(tuán)隊(duì)內(nèi)部需要就核心字段集達(dá)成一致。3.3 向后兼容性與漸進(jìn)式采用Lore 協(xié)議被設(shè)計為對現(xiàn)有工具鏈完全透明。對于不識別## Lore-Context區(qū)塊的普通 Git 客戶端、代碼托管平臺GitHub/GitLab或 CI/CD 系統(tǒng)它們只會將其視為提交信息中的普通 Markdown 注釋完全不影響瀏覽和顯示。只有那些集成了 Lore 協(xié)議解析器的 AI 助手或?qū)ｉT工具才會去解析并利用其中的結(jié)構(gòu)化信息。這意味著團(tuán)隊(duì)可以漸進(jìn)式地采用 Lore?？梢詮淖钪匾摹⒓軜?gòu)復(fù)雜的模塊開始要求相關(guān)提交附帶 Lore 上下文。甚至可以先由人類編寫逐漸訓(xùn)練 AI 助手學(xué)會在生成提交時自動填充部分字段如根據(jù)代碼 Diff 和對話歷史推斷change_intent和dependencies。4. 實(shí)戰(zhàn)將 Lore 協(xié)議集成到 AI 編碼助手工作流中理念再好也需要落地。要讓 Lore 發(fā)揮作用我們需要對現(xiàn)有的 AI 編碼助手進(jìn)行“賦能”讓它們能夠理解和生成 Lore 格式的提交信息。這里不涉及具體某個 AI 產(chǎn)品的內(nèi)部實(shí)現(xiàn)而是提供一套通用的集成思路和工具鏈設(shè)想。4.1 為 AI 助手構(gòu)建“Lore 感知”上下文當(dāng) AI 助手如 Copilot、Cursor、Claude Code 等被要求修改代碼或?qū)彶橐粋€ Pull Request 時它的上下文通常包括當(dāng)前文件、打開的相關(guān)文件、以及可能的終端輸出。為了集成 Lore我們需要一個中間件或插件來增強(qiáng)它獲取的上下文。這個中間件的工作流程如下監(jiān)聽事件當(dāng) AI 助手的上下文需要更新時例如切換到新文件、執(zhí)行g(shù)it log命令、查看某個函數(shù)歷史中間件被觸發(fā)。分析目標(biāo)確定用戶當(dāng)前關(guān)注的文件、函數(shù)或代碼行。檢索 Lore運(yùn)行一個后臺命令使用git blame或git log -p -S等命令找到最近修改目標(biāo)代碼的提交哈希。然后獲取這些提交的完整信息。解析與過濾解析這些提交信息提取出## Lore-Context區(qū)塊。將多個相關(guān)提交的 Lore 上下文合并、排序形成一個連貫的“歷史決策敘事”。注入提示詞將提取到的結(jié)構(gòu)化 Lore 上下文以清晰的文本摘要形式作為系統(tǒng)提示詞System Prompt的一部分或額外的上下文注入到 AI 助手的會話中。例如當(dāng)開發(fā)者將光標(biāo)定位到一個復(fù)雜的數(shù)據(jù)庫查詢函數(shù)時AI 助手側(cè)的提示詞可能會被自動追加這樣一段信息【相關(guān)歷史決策上下文 (來自Lore)】 - 提交 a1b2c3d (feat): 首次實(shí)現(xiàn)此查詢。決策在“使用ORM原生查詢”與“手寫SQL”間選擇了“手寫SQL”原因需要利用數(shù)據(jù)庫特定的窗口函數(shù)以獲得最佳性能。 - 提交 e5f6g7h (perf): 為此查詢添加了復(fù)合索引。約束必須保持查詢響應(yīng)時間 p95 50ms。新增索引 idx_user_status_created。 - 提交 i8j9k0l (fix): 修復(fù)了在用戶狀態(tài)為‘PENDING’時可能出現(xiàn)的重復(fù)計數(shù)問題。根因?qū)?LEFT JOIN 條件理解有誤。關(guān)聯(lián)測試文件test_complex_query.py。現(xiàn)在當(dāng)開發(fā)者或另一個 AI 任務(wù)問“如何優(yōu)化這個函數(shù)”時AI 助手已經(jīng)知道1這個函數(shù)對性能很敏感有明確的延遲目標(biāo)2已經(jīng)有一個為它服務(wù)的特定索引3這里曾經(jīng)有一個關(guān)于 JOIN 條件的微妙 Bug。它給出的建議就會更有針對性避免提出“換成 ORM 查詢”這種與歷史決策沖突的方案。4.2 訓(xùn)練 AI 助手生成 Lore 格式的提交反過來我們更希望 AI 助手在完成代碼修改后能主動生成包含豐富 Lore 上下文的提交信息。這需要一些引導(dǎo)和模板。我們可以創(chuàng)建一個預(yù)定義的提示詞模板在請求 AI 生成提交信息時使用請你作為資深開發(fā)者為剛才完成的代碼變更撰寫 Git 提交信息。 請遵循以下格式 **提交標(biāo)題**type(scope): 簡短描述 (使用Conventional Commits類型) **提交正文** 首先用一段話概括本次變更的內(nèi)容、動機(jī)和影響。 然后請生成一個結(jié)構(gòu)化的 **## Lore-Context** 區(qū)塊。請基于我們的開發(fā)對話和代碼變更盡可能填充以下JSON字段 { “protocol_version”: “0.1.0”, “change_intent”: “bug_fix|feature_implementation|performance_optimization|...”, “requirements”: [“關(guān)聯(lián)的任務(wù)ID如JIRA-XXX”], “constraints”: { “backward_compatibility”: “must|optional|breaking”, // 其他關(guān)鍵約束如性能目標(biāo)、安全要求等 }, “decisions”: [ // 列出1-2個在實(shí)現(xiàn)過程中做出的關(guān)鍵設(shè)計或技術(shù)決策 { “problem”: “遇到的問題”, “options”: [“方案A”, “方案B”], “chosen”: “選擇的方案”, “reason”: “詳細(xì)的選擇理由包括權(quán)衡” } ], “dependencies”: [“依賴的前序提交哈希可選”], “tests”: { “added”: [“新增的測試文件”], “updated”: [“更新的測試文件”] } } **最后**在 Lore 區(qū)塊后可以補(bǔ)充更詳細(xì)的實(shí)現(xiàn)說明。通過多次使用這樣的模板AI 助手會逐漸學(xué)習(xí)到團(tuán)隊(duì)對結(jié)構(gòu)化上下文的需求。更進(jìn)一步可以開發(fā)一個 IDE 插件或 Git Hook如prepare-commit-msg在提交時自動調(diào)用 AI API根據(jù)暫存區(qū)的 Diff 和最近的開發(fā)對話歷史建議一個填充了部分字段的 Lore 提交信息草稿供開發(fā)者審核和修改。4.3 工具鏈設(shè)想Lore 命令行工具與 CI 集成為了便于管理和利用 Lore 數(shù)據(jù)可以開發(fā)一個簡單的命令行工具lore-clilore-cli parse commit-hash解析指定提交的 Lore 上下文并以友好格式打印。lore-cli search --intentbug_fix --filesrc/utils.py搜索修改過指定文件且意圖為 bug_fix 的所有提交及其 Lore。lore-cli graph commit-hash生成該提交依賴的決策圖基于dependencies和decisions字段。在 CI/CD 流水線中可以集成 Lore 檢查提交信息 lint檢查提交信息是否包含有效的 Lore 區(qū)塊非強(qiáng)制但可提示。約束驗(yàn)證如果 Lore 中聲明了performance_targetCI 可以自動運(yùn)行對應(yīng)的性能測試驗(yàn)證變更是否仍滿足目標(biāo)并在 PR 中報告。影響分析當(dāng)新的 PR 修改了某個文件CI 可以自動找出該文件歷史上所有包含 Lore 的提交提取關(guān)鍵約束和決策作為 PR 審查的補(bǔ)充信息提醒審查者注意。5. 潛在挑戰(zhàn)、應(yīng)對策略與未來展望任何新范式都會面臨挑戰(zhàn)Lore 也不例外。最大的挑戰(zhàn)可能來自于“額外的開銷”和“一致性維護(hù)”。挑戰(zhàn)一編寫結(jié)構(gòu)化上下文增加了提交成本。應(yīng)對策略這需要文化轉(zhuǎn)變和工具輔助。初期可以將其視為一種“代碼注釋”但注釋的是“變更意圖”而非具體實(shí)現(xiàn)。工具輔助是關(guān)鍵如上文所述的 AI 生成建議、IDE 模板片段可以大幅降低編寫成本。團(tuán)隊(duì)可以從最關(guān)鍵、最復(fù)雜的模塊開始試行讓成員體驗(yàn)到“閱讀 Lore 帶來的上下文紅利”大于“編寫 Lore 的成本”從而形成正向循環(huán)。挑戰(zhàn)二如何保證 Lore 信息的準(zhǔn)確性和及時更新應(yīng)對策略Lore 信息應(yīng)被視為與代碼注釋同等級別的“文檔”在代碼審查Code Review時一并審查。審查者需要檢查 Lore 中的decisions是否合理、constraints是否準(zhǔn)確。當(dāng)后續(xù)重構(gòu)使得某個 Lore 上下文過時應(yīng)該在新的提交中更新或注明。這類似于更新過時的代碼注釋是良好開發(fā)實(shí)踐的一部分。挑戰(zhàn)三協(xié)議碎片化與工具生態(tài)。應(yīng)對策略Lore 作為一個開放理念其具體協(xié)議格式可以社區(qū)化?？梢越⒁粋€簡單的規(guī)范網(wǎng)站定義核心字段和擴(kuò)展機(jī)制。關(guān)鍵是要保持極簡和可擴(kuò)展。工具生態(tài)會隨著采用度的提高而自然生長初期可以由團(tuán)隊(duì)內(nèi)部開發(fā)簡單的腳本和插件。未來展望Lore 的終極愿景是讓項(xiàng)目的 Git 倉庫成為一個真正意義上的、富含語義的“知識圖譜”。AI 助手可以像查詢數(shù)據(jù)庫一樣查詢項(xiàng)目歷史“這個模塊為什么采用了這種設(shè)計模式”“修改這個函數(shù)需要特別注意哪些性能約束”“歷史上修復(fù)這類 Bug 通常涉及哪些文件”。更進(jìn)一步這或許會催生一種新的“基于歷史的編程”范式。開發(fā)者或 AI 在動手前先“咨詢”項(xiàng)目歷史通過 Lore獲得經(jīng)過時間檢驗(yàn)的設(shè)計模式和避坑指南從而寫出更穩(wěn)健、更符合項(xiàng)目氣質(zhì)的代碼。Git 提交信息這個我們?nèi)粘９ぷ髦凶钇椒驳脑鼗蛟S正是連接人類開發(fā)者智慧與 AI 助手能力實(shí)現(xiàn)高效、可傳承協(xié)作的那座橋梁。它的價值遠(yuǎn)不止于那一行g(shù)it log --oneline的輸出。