CONTRIBUTING_ZH.md

MiniCode 贡献规范

欢迎为 MiniCode 提交 PR。

本项目有明确的边界：它需要保持小、清晰、易读，并且在设计方向上尽量贴近 Claude Code 的核心思路。

这份文档用于说明贡献时的基本要求。

核心原则

1. 保持项目轻量

请尽量避免引入过于复杂的设计变动。

MiniCode 有意保持为一个小型项目。新增改动应尽量保持：

• 代码库体量紧凑
• 控制流直接
• 理解成本低
• 用户操作到模型循环、工具调用、UI 更新之间的链路清晰

如果一个改动会引入很重的抽象层、很深的间接跳转，或者明显增加系统复杂度，通常不太适合这个项目，除非它确实是必要的。

2. 与 Claude Code 的设计方向保持趋同

由于项目性质，新增特性应尽量与 Claude Code 源码本身的设计方向趋同或相似。

这并不意味着机械照搬，而是意味着：

• 优先借鉴相近的架构思路，而不是发明完全无关的新模式
• 在移植功能时，尽量保持相同的心智模型
• 如果某个功能明显偏离 Claude Code 的风格，需要有足够强的理由

MiniCode 是一个轻量借鉴版，不是一个完全独立路线的 terminal agent 项目。

贡献要求

3. 优先做小步、渐进式修改

PR 应该尽量容易 review。

请优先采用：

• 聚焦型改动，而不是大范围重构
• 一个 PR 只解决一个功能或一个问题
• 能用较短说明讲清楚的改动

如果一个功能较大，请尽量拆成多个小步骤推进。

4. 尽量保持现有交互节奏

如果改动涉及 CLI、TUI、tool loop、权限系统、MCP 接入或 skills 行为，请尽量：

• 保持当前面向用户的交互节奏
• 不要轻易破坏现有命令和工作流
• 如果确实改变了行为，需要同步说明

5. 不要随意削弱安全边界

MiniCode 当前的重要边界包括：

• 文件修改前 review
• 路径访问控制
• 命令执行控制
• 审批流程

如果改动会影响这些边界，请在 PR 中明确说明原因和影响。

6. 可读性优先于炫技

这个项目本身也用于学习和参考。

因此请优先选择：

• 可读代码，而不是过度技巧化的写法
• 显式的数据流，而不是隐藏式魔法
• 简单工具函数，而不是过早抽象

如果一个设计更难理解，那它也应该带来足够明确的收益。

7. 依赖保持克制

新增依赖前，请先判断：

• 现有代码能否完成同样的事情
• 这个依赖是否符合项目轻量定位
• 它是否会让维护和理解成本明显上升

如果收益不大，请尽量不要引入新依赖。

8. 行为变化要同步更新文档

如果 PR 改变了面向用户的行为，请同步更新相关文档。

常见包括：

• README.md
• README.zh-CN.md
• 架构文档
• 新命令或新配置示例

9. 提交前先完成基本验证

在打开 PR 之前，请至少确认：

• 代码可以正常构建
• 相关行为已经过验证
• npm run check 通过

如果某部分暂时没有验证，请在 PR 描述中明确写出来。

10. 新增特性前先查看 issue

如果是新增特性，请先查看仓库里的 issue。

这样可以避免重复开发，也能让实现方向和当前路线图保持一致。

更推荐的流程是：

• 先确认是否已经有对应 issue
• 先确认是否已经有人认领该工作
• 如果是中大型特性，而仓库里还没有对应 issue，建议先提 issue
• 提交 PR 时，尽量关联对应 issue

如果只是很小的修复或文档改动，可以根据情况直接提 PR。

比较适合的贡献方向

比较欢迎的贡献包括：

• 交互细节打磨
• tool loop 稳定性增强
• 权限与 review 流程改进
• MCP 兼容性增强
• skills 支持增强
• 与 Claude Code 设计方向一致的架构细化
• 文档清晰度提升

通常不太适合的改动

下面这些方向通常需要更强的理由：

• 明显增大系统复杂度的大重构
• 让 MiniCode 偏离 Claude Code 设计方向的功能
• 实际收益不明显但抽象层很重的设计
• 为了较小收益引入较重依赖
• 让项目变得更难阅读、更难二次开发的改动

PR 说明建议

一个好的 PR 描述最好能简要说明：

• 改了什么
• 为什么要改
• 如果适用，对应的是哪个 issue
• 为什么这次改动仍然保持轻量
• 它和 Claude Code 的设计方向如何对应
• 做了哪些验证
• Reviewer 在本地如何复现和验证这次改动

感谢你帮助 MiniCode 持续演进，同时也帮助这个项目保持清晰和克制。