RepoResident：让AI编码助手成为真正的代码库维护者

RepoResident是一个Git原生的项目智能框架，旨在解决Claude Code、Codex等AI编码助手的"记忆困境"——每次会话AI对项目目标、状态、决策等一无所知的问题。通过结构化文档和分层工作流，它让AI获得项目感知能力，实现50%以上Token使用量降低和更高质量的代码设计。

AI编码助手虽改变开发方式，但存在根本性问题：每次新会话AI像"局外人"，对项目方向、状态、决策等缺乏认知。传统交互方式存在诸多局限：响应孤立提示、重复探索代码库、即兴决策、重新考虑已确定方案等。RepoResident通过结构化文档将通用编码代理转变为项目感知型维护者，让AI基于项目目标和实时状态推理。

核心理念：让AI从项目中推理而非仅依赖提示。 分层知识架构：

• 项目感知层（L0-L1）：CLAUDE.md（操作规则）、STATE.md（当前状态）
• 任务工作流层（L2）：特定任务的执行步骤文件
• 深度知识层（L3）：MAP.md（模块映射）、PROJECT.md（架构约束）、DECISIONS.md（技术决策）等
• 源代码层（L4）：针对性读取而非全面扫描 工作流纪律：为功能开发、已知修复、未知缺陷、重构、代码审查等任务定义专属流程。

RepoResident经真实项目验证的效果包括：

1. Token使用量降低50%以上（定向导航减少重复探索）；
2. 提示缓存复用率更高（稳定指令和工作流提升命中率）；
3. 技术设计更强（考虑项目目标、架构、约束等）；
4. 减少捷径驱动实现（拒绝存根、静默范围缩减）；
5. 代码更可维护（优先可读性、测试、一致性）。

质量契约：明确工程期望，如无存根实现、必要复杂性需设计论证、行为变更含失败测试、边界处理全面、代码优先可读性等。 多工具兼容性：支持Claude Code（CLAUDE.md）、Codex（AGENTS.md）、Cursor（AGENTS.md/CLAUDE.md）等工具，框架与模型无关。

新建项目：

1. GitHub选择"Use this template"创建仓库；
2. 用编码代理打开，提供项目简介（目标、栈、约束）执行引导。 现有项目：
3. 复制CLAUDE.md、AGENTS.md、.agent/到根目录；
4. 代理执行"Bootstrap: adopt this repository"构建初始映射。

团队模式：默认分支针对单个写入者，multi-team分支添加咨询看板、分支集成工作流等。 局限性：

• 非安全边界，编码代理仍可能犯错；
• 项目知识需会话维护才有用；
• 定量改进因代码库、模型、任务而异；
• 并行分支需用团队模式。

RepoResident代表AI协作新范式：将AI从临时助手转变为长期项目维护者。通过结构化文档和分层架构，AI获得持续项目感知能力，做出更符合目标的决策。对采用AI编码助手的团队，它提供实战框架，降低Token使用、提升代码质量，成为开发流程可靠伙伴。