Clean-Coder-AI：让 AI 同时当项目经理和程序员的开发工作流

你有没有遇到过这种情况：给 AI 一个模糊的需求，它噼里啪啦写了一堆代码，但当你真正去运行的时候，文件结构混乱、依赖关系一团糟、变量命名随心所欲，最终还是得自己返工？这几乎是所有 AI 编程助手的通病——它们擅长"写代码"，却不擅长"做项目"。

Clean-Coder-AI 试图从根本上解决这个问题。它不是一个普通的代码生成工具，而是一套双模式 AI 开发工作流：Manager 模式扮演项目经理 + 总工程师，负责将需求拆解成 Todoist 任务并制定开发计划；Single Task Coder 模式则像一群高度协作的程序员，分别负责调研、规划、执行和调试。

背景：从"一人团队"到"AI 团队"

Clean-Coder-AI 的诞生背景很有意思。作者 Grigorij Dudnik 是一个独立开发者，在经历了无数次"让 AI 写代码→运行报错→修复报错→引入新 Bug→再修复"的循环后，开始思考：为什么不让 AI 也像真实团队一样工作？

真实世界的软件开发，从来不是一个人从零写到尾。产品经理出需求 → 项目经理拆任务 → 前端后端各自实现 → 测试介入 → 回归修复。Clean-Coder-AI 正是将这个流程 AI 化：用 LangGraph 实现状态机驱动的多 Agent 协作，每个 Agent 各司其职，通过 LangChain 的 Tool Calling 机制相互配合。

核心架构：双模式 + 多 Agent 协作

项目提供两种启动模式，分别对应不同的使用场景：

Manager 模式：多文件大型项目的指挥官

Manager 是整个系统的"大脑"，基于 LangGraph 构建了一个复杂的状态机。当用户输入一个项目需求时，它会：

1. Researcher Agent 先对需求进行调研，通过 Playwright 搜索相关技术文档和最佳实践，收集图片和参考资料
2. Planner Agent 根据调研结果制定开发计划，将项目拆解成多个 Todoist 任务，并为每个任务规划实现步骤（伪代码形式）
3. Manager 协调整个流程，维护任务状态，处理用户交互

Manager 模式需要配置 Todoist API Key 和 Project ID——它会把开发计划直接写入你的 Todoist 项目，你可以在 Todoist App 中直观地看到每个任务的进度，感受"AI 在给你打工"的奇妙体验。

Single Task Coder 模式：专注单任务的高效执行者

当你不需要完整的项目管理流程，只需要快速完成一个具体任务时，Single Task Coder 模式更为轻量。它包含以下 Agent：

• Researcher：调研任务背景，收集相关文件信息
• Planner：规划具体实现步骤
• Executor：执行代码编写任务
• Debugger：运行测试、分析报错、修复 Bug
• Frontend Feedback（可选）：如果配置了前端截图服务，还能对前端界面进行视觉反馈

RAG 驱动的代码理解

Clean-Coder-AI 还内置了一套基于 ChromaDB 的 RAG 系统。系统启动时会对工作目录中的所有文件进行语义索引（通过 code_splitter 分块 + embedding），当 Planner 生成代码计划时，会先通过 RAG 检索相关文件的上下文，确保生成的代码与现有代码库风格一致、依赖关系正确。这是一个很聪明的设计——它让 AI 不再是"闭着眼睛写代码"，而是真正"理解你的项目再动手"。

技术栈：LangGraph 全家桶

项目的技术选型非常务实，核心依赖清晰：

项目使用 Python-dotenv 管理环境变量，提供了完整的 .env.template，开发者只需要填入 API Key 即可运行。

部署体验：Docker Compose 一键启动

Clean-Coder-AI 提供了 docker-compose.yml，定义了两个服务：

• manager：运行 Manager 模式，监听 manager.py 入口
• single_task_coder：运行 Single Task Coder 模式，监听 single_task_coder.py 入口

Docker 配置将当前目录挂载到容器内，并挂载一个可配置的 WORK_DIR 用于代码输出。对于没有深度定制需求的开发者来说，拉取镜像 + 配置 API Key 即可启动。唯一的门槛是：你需要同时拥有 OpenAI/Anthropic API Key 和 Todoist 账号，缺少后者会导致 Manager 模式的规划功能不可用。

局限与争议

需要客观指出这个项目的一些局限：

API Key 依赖严重：整个系统的能力上限完全取决于你拥有的 LLM API Key。Claude 3.5 Sonnet 和 GPT-4o 效果差异明显，在一些需要复杂推理的规划任务上，小模型的规划质量会明显下降。

Todoist 强绑定：Manager 模式对 Todoist 的依赖不只是"锦上添花"，而是核心功能。没有 Todoist，Planner 产出的计划无法持久化，整个 Manager 模式的价值大打折扣。

代码执行安全：Executor Agent 生成的代码会通过 subprocess 在本地执行。虽然有 Ruff + Pyright 的静态检查作为安全门卫，但 AI 生成的代码执行仍存在风险，建议在隔离环境中使用。

没有 Web UI：这是一个纯 CLI 工具，虽然命令行界面用 Rich 和 Pygments 做了美化，但对于不熟悉终端的用户来说上手成本较高。

行业意义：多 Agent 协作的工程化实践

Clean-Coder-AI 代表了 2024-2025 年 AI 编程工具的一个重要方向：从"单 Agent 单次调用"向"多 Agent 流水线协作"演进。AutoGPT 时代的多 Agent 探索虽然想法超前，但工程化程度不足。Clean-Coder-AI 则通过 LangGraph 的状态机约束，加上 RAG 的上下文增强，以及 Todoist 的外部系统集成，走出了一条更工程化的路线。

项目目前 Star 数接近 600，对于一个相对小众的"AI 开发流程"工具来说，已属不错的成绩。它的核心价值在于证明了：AI 编程工具的天花板，不在于模型本身有多强，而在于工作流设计得有多合理。如果你正在探索 AI 原生开发工具链，这个项目值得 clone 下来仔细研究。