本文所提到的开发模式并非适用于所有项目，即使是笔者的个人项目，也并非全部采用了这种模式，这种模式仅适合作为一种兼顾快速试错与长期维护的过渡期实践参考。

VibeCoding很爽

无论怎么样，核战争还没有爆发，已有的科技浪潮不会退去，Agent生产代码的占比只会越来越多。

黑客们将英伟达的卡对接到了MacOS系统，暗黑破坏神2被移植到了iPad，这些都很让人兴奋，这是应用开发者最好的时代，让人感觉到自己无所不能，欠缺的只有精力。

VibeCoding很爽，对于已经习惯了11点多睡觉，6点左右起床的笔者来说，也曾狂热到1点多对话，把电脑放到客厅，早上起来迫不及待地继续对话。

这让我一个工程师，更想去构筑自己使用的工具。这一年来，我刷新了个人网站，还写了一个桌面工具，做了一些demo，觉得Postman在公司内不好用还写了一个类似Postman的工具。

题外话，为什么个人Vibe的效率如此之高？

这涉及到很多点：自我驱动、掌控方向、接受不被理解的代码提交、接受可能存在bug的代码提交。最关键的是 无需和他人沟通，你要说服的只有自己。

工程师的纠结

但我并不是完全不懂技术的用户，笔者很懂CleanCode、软件工程，是经验丰富的编码工程师（有些自夸，哈哈），笔者的代码风格极其一致，对不同编程语言的最佳范式有很深的理解。Library/方法的边界，重试、超时？异常信息该怎么写？如何分包，包名该用单数还是复数？大括号后面要不要有换行？参数的顺序该如何书写？什么东西要不要提交到代码仓？pom文件怎么写最好？Git commit记录怎么写清晰整洁？

笔者也曾发出这样的感慨 笔者又想快速把东西做出来自己用（不然始终在消耗时间，又拿不到成果），又想争取人能懂这个代码，有很好的代码结构，适合演进。最终采取了一个main、dev双分支开发的策略。

main可信，dev放飞实践

分支说明

main分支负责长期可信维护，代码结构要求清晰精美、易于维护、模块化。

dev负责快速迭代出功能，代码不追求看懂，结构大致符合项目整体规划即可。

dev分支应该以尽可能高的频率不断rebase main分支的代码，一些简单清晰的提交，也可以直接提交到main分支。

main分支维护心得

main分支一定要良好地组织，合理地拆分文件、模块。这样才能更易于看懂，也能尽量避免main、dev分支合并的冲突。

AGENTS.md增加实现指南

这是笔者在实际项目中取得不错效果的提示词

## Implementation Guidance  
  
- Implement features elegantly and with extensibility in mind. Split code into focused files/modules when that keeps the  
  design clearer, reduces coupling, or makes future feature types easier to add.  
- When a task explicitly calls for refactoring or migration, treat the target architecture as the source of truth rather  
  than preserving the old structure by default. Refactor boldly: move responsibilities to the right layer, delete  
  redundant code, split or merge modules where it clarifies ownership, and leave compatibility shims only when they are  
  necessary for a staged transition.  
- When the user explicitly asks not to preserve compatibility aliases during a rename or migration, remove the old names  
  across code, docs, command surfaces, and tests instead of keeping transitional aliases.

这段提示词主要表达了几个意思：在有必要的时候拆分文件和模块，让职责清楚；明确要求重构时，可以调整原来的结构；明确不需要保留旧接口时，就把代码、文档和测试里的旧名字一起清理掉。

持续完善AGNETS.md

main分支一定要做好模块化，比如在Vibe一部分前端页面的时候，生成一个非常大的单体CSS文件，就立刻在AGENTS.md增加要求，结构化拆分CSS。

- Keep CSS at the same abstraction level as the UI it describes. Document/window baseline rules belong in a tiny global
  file such as `ui/window.css`; app shell layout, shell-scoped variables, panel backgrounds, borders, and resize handles
  belong in `App.css`; component visuals and component-specific responsive rules belong next to that component. Do not
  use `App.css` or vague shared `styles/` files as import aggregators or dumping grounds for lower-level component
  styles. When moving styles to their owning layer, delete obsolete shared files instead of keeping empty buckets.

利用docs维护

过去维护与代码对应的docs非常费劲，大家都不愿意改动两个地方，于是你能看到很多工具，都是从现有的代码生成文档，或者是从现有的文档生成代码。

这些方式现在依然很好，不过也存在明显的缺陷，比如需要高度结构化，适用范围很窄。

那么现在，很多东西都可以通过docs结构化，比如你有5个主要界面，每个界面的内容，定位，其实都可以通过docs以某种松散的格式提交，用来人工审核、Review，也方便指引Agent开发。（让Agent修改完代码刷新文档，或者修改文档并刷新代码就可以了，很方便）

以笔者开发的小工具为例，每个cli命令都有一个松散格式的文档，用来指引Agent开发，例如：

# GitCode  

The `gitcode` module contains commands for GitCode-related integrations in ChuQin.  

## Commands  

- `chuqin gitcode repo list`: List the authenticated user's GitCode code repositories.  
- `chuqin gitcode repo delete <owner> <repo>`: Delete a GitCode repository by owner and repository path.  

## Configuration  

These commands require a GitCode personal access token in `.chuqin/config.toml`:

[gitcode]  
token = "your-token"  
username = "your-username"

从dev逐步合入main

明确了main上希望维护的东西，再回头看dev，就可以逐步挑选值得保留的成果。

一些看得非常清楚的改动，可以比较快地整理合入，比如新增了一个职责独立的插件等。

但如果dev已经难以理解，也可以让Agent帮忙分析，寻找第一个适合整理到main的patch。

main分支同步到dev

在dev分支上维护一个线性清晰的提交是几乎不可能的，不必做这种费时费力的尝试，笔者在实践中，仅在dev分支上维护一个巨大的commit，不断从main分支上rebase即可。

git pull --rebase origin main

这有点类似于维护自己的fork版了 :)