1. 项目概述为AI智能体开发量身定制的仓库规范套件如果你和我一样在日常开发中深度依赖Claude Code、Cursor这类AI编程助手那你一定遇到过这样的困境助手虽然能理解单行代码但对整个项目的上下文、待办任务、知识沉淀却常常“断片”。每次开启新对话都得重新解释一遍项目结构、当前在做什么、有哪些坑。这就像和一个记忆力只有七秒的搭档合作效率大打折扣。agent-repo-kit正是为了解决这个痛点而生的。它不是另一个花哨的AI工具而是一套面向仓库的、与具体AI助手运行时解耦的规范与工具集。你可以把它理解为给项目仓库穿上了一件“AI可读”的标准制服。这套制服定义了三个核心模块一个扁平文件的任务追踪器.tickets/、一个由LLM维护的知识库.wiki/以及一套用于审计和引导规范落地的自动化工作流。最吸引我的地方在于它的“运行时无关”设计。无论你用的是Claude Code、Codex还是未来的某个新工具只要它们遵循基本的文件读写和命令执行能力就能利用这套规范。这避免了被单一工具锁定的风险让项目本身的结构成为AI协作的第一等公民。接下来我将带你深入这套工具的设计哲学、实操部署以及我踩过的一些坑让你能快速在自己的项目中用起来。2. 核心设计哲学为什么需要“AI可读”的仓库规范在深入代码之前我们得先想明白一个问题为什么传统的项目结构对AI不友好我们已有的README.md、docs/、TODO.md难道不够吗从我实际与AI协作的经验来看传统文档存在几个关键缺陷。首先信息是静态且割裂的。README通常介绍项目TODO.md列出任务但任务的状态进行中、阻塞、已完成、优先级、关联的知识点比如“为什么选择这个库而不是另一个”是分散的。AI在理解“我们现在正在做什么以及为什么这么做”时需要像侦探一样拼凑碎片。其次缺乏机器可解析的结构。AI理解自然语言很棒但对于任务状态、依赖关系这类结构化信息纯文本描述效率低下且容易歧义。一个写着“修复登录BUG”的TODOAI无法自动关联到相关的代码文件、之前的讨论记录或测试用例。agent-repo-kit的设计哲学可以概括为三点状态外显化将开发流程中的“任务状态”明确地建模成一个状态机并用文件系统来体现。一个任务文件从.tickets/open/移动到.tickets/in-progress/再移动到.tickets/done/这个物理路径的变化就是最清晰的状态信号无论是人还是AI都一目了然。知识结构化鼓励将临时性的、聊天记录里的“灵光一现”沉淀为结构化的知识条目.wiki/。这些条目有固定的Frontmatter元数据比如tags、related_tickets使得知识之间可以互相关联形成一个可检索、可推理的网络。契约可验证这套规范本身是一份“契约”。项目是否遵循了契约遵循了多少可以通过ark命令行工具进行自动化审计和打分ark audit。这为团队协作和CI集成提供了客观的质量门禁。这种设计让AI从一个被动的“代码补全器”转变为一个能主动理解项目上下文、参与任务规划和知识管理的“协作者”。它知道当前冲刺的目标是什么有哪些已知的解决方案以及项目的编码规范是什么。3. 快速上手指南十分钟内为你的仓库注入AI协作能力理论讲完了我们直接动手。假设你有一个现有的Go项目想快速接入agent-repo-kit。整个过程非常快核心就是两个命令安装工具然后初始化仓库。3.1 环境准备与工具安装首先你需要安装核心的ark命令行工具。官方提供了最便捷的一键安装脚本curl -sSL https://raw.githubusercontent.com/gh-xj/agent-repo-kit/main/install.sh | sh这个命令会从GitHub Releases下载预编译的ark二进制文件并安装到~/.local/bin/目录下。安装完成后记得确认该目录在你的系统PATH环境变量中。可以执行ark --version来验证安装是否成功。注意一键安装脚本默认需要网络通畅以访问GitHub。如果你的环境受限或者希望从源码构建可以克隆仓库后使用./install.sh --from-source但这需要你的系统已安装Go 1.25或更高版本。接下来你需要为你使用的AI助手运行时安装对应的“技能”Skills。技能是agent-repo-kit将规范暴露给特定AI助手如Claude Code的适配模块。以同时安装给Claude Code和Codex为例npx skills add gh-xj/agent-repo-kit -g -a claude-code -a codex --skill * -y这个命令通过npx调用了一个技能管理工具它会-g进行全局安装。-a claude-code -a codex同时为claude-code和codex两个运行时安装适配器。--skill *安装该仓库提供的所有技能。-y自动确认无需交互。执行成功后这些技能会被复制到对应运行时管理的目录下例如~/.claude/skills/。安装完成后通常需要重启你的AI助手客户端如Cursor或Claude Code编辑器以便它重新扫描并加载新技能。3.2 初始化你的项目仓库工具就绪后进入你想要改造的项目根目录执行初始化命令。这里我以一个有Go和TypeScript-React代码的混合项目为例cd /path/to/your-project ark init --profiles go,typescript-react这个ark init命令是魔法发生的核心。它会在当前目录默认--repo-root为当前目录下创建一整套规范文件。--profiles参数至关重要它告诉工具你的项目主要技术栈工具会根据这些信息生成更贴合的文档模板和检查规则。执行后你会看到类似以下的输出并发现仓库里多了一些新的文件和目录✅ 创建 .convention-engineering.json ✅ 创建 .tickets/ 目录结构 ✅ 创建 .wiki/ 目录结构 ✅ 更新 docs/ 分类文档 ✅ 写入 AGENTS.md 和 CLAUDE.md ✅ 生成 Taskfile.yml 约定任务 初始化完成请运行 task verify 来验证约定。现在你的仓库已经具备了AI协作的基础设施。最重要的两个新增目录是.tickets/里面按照状态open/,in-progress/,done/组织了任务文件。.wiki/用于存放项目知识文档。同时根目录下会生成一个Taskfile.yml这是用 Go Task 定义的任务运行器它封装了所有与规范相关的操作命令如验证、测试、清理等。3.3 验证与初体验初始化完成后立即运行验证命令确保一切就绪task verify这个命令会执行一系列检查约定的文件结构是否正确、Taskfile语法是否合法、.wiki/中的文档格式是否符合要求等。如果看到所有检查都通过✅恭喜你你的仓库已经成功“AI化”。现在你可以尝试在AI助手中与它互动了。例如在Claude Code中你可以直接说“查看一下当前有哪些开放的任务。” 或者 “我想开始处理一个任务该怎么做” 由于技能已安装AI助手能够理解这些指令并去读取.tickets/open/目录下的文件来回答你。4. 核心模块深度解析.tickets与.wiki如何工作初始化只是第一步要真正用好agent-repo-kit必须理解其两个核心模块的设计细节和运作机制。这决定了你与AI协作的流畅度。4.1 .tickets基于文件系统的轻量级任务追踪.tickets/目录摒弃了复杂的数据库或Web服务采用极简的“文件即状态”理念。其目录结构如下.tickets/ ├── open/ # 待开始的任务 │ ├── TICKET-001-add-user-auth.md │ └── TICKET-002-fix-api-timeout.md ├── in-progress/ # 进行中的任务 │ └── TICKET-003-refactor-db-layer.md ├── done/ # 已完成的任务按日期归档 │ └── 2024-05-27/ │ └── TICKET-000-initial-setup.md ├── _templates/ # 任务模板 └── Taskfile.yml # 任务相关的自动化脚本一个任务文件里有什么每个任务都是一个Markdown文件但包含结构化的FrontmatterYAML格式和自由格式的描述。例如一个TICKET-001-add-user-auth.md文件可能以如下内容开头--- id: TICKET-001 title: “实现用户认证模块” status: open priority: high assignee: “yourname” created: 2024-05-27T10:00:00Z requires: [] blocks: [] tags: [auth, backend, breaking] --- **描述** 我们需要为应用添加基于JWT的用户登录和注册功能。 **验收标准** - [ ] 用户可以使用邮箱和密码注册 - [ ] 注册后发送验证邮件 - [ ] 用户可以使用邮箱密码登录并获取JWT - [ ] API端点需要JWT令牌保护 ...为什么这样设计人机皆可读对于开发者用任何文本编辑器都能查看和编辑。对于AIMarkdown易于解析Frontmatter提供了明确的元数据字段。状态变更即文件操作将一个任务从“待办”变为“进行中”只需要用mv命令或AI执行等价的文件操作将文件从open/移动到in-progress/。这比在Web界面点击按钮更符合开发者的终端工作流。易于集成与版本控制所有任务历史都通过Git管理谁在什么时候改了什么都一清二楚。CI/CD可以轻松地监听.tickets/目录的变化触发自动化流程如每当有任务被移入done/就自动生成变更日志。配套的Taskfile自动化.tickets/Taskfile.yml预置了许多实用命令。例如task -d .tickets test运行所有任务场景的测试确保任务描述格式正确等。task -d .tickets new --title \我的新任务\基于模板快速创建一个新任务文件。task -d .tickets stats生成任务统计报告各状态数量、平均周期等。4.2 .wiki由LLM维护的活体知识库如果说.tickets管理“做什么”那么.wiki/就管理“为什么”和“怎么做”。它的目标是捕获那些容易丢失在聊天记录或开发者脑海中的上下文决策和解决方案。.wiki/同样采用文件系统结构但鼓励按主题分类.wiki/ ├── decisions/ # 架构决策记录 │ └── 2024-05-20-why-we-chose-postgres.md ├── how-to/ # 操作指南 │ ├── set-up-dev-environment.md │ └── deploy-to-staging.md ├── references/ # 技术参考 │ └── api-rate-limiting-spec.md ├── _templates/ # 知识页面模板 └── Taskfile.yml # 知识库维护任务知识页面的核心可引用的原子单元每个.wiki页面也是一个Markdown文件但其Frontmatter要求包含citation引用字段。这是为了让AI或开发者能明确地引用某条知识。--- title: “为什么选择PostgreSQL而非MySQL” type: decision date: 2024-05-20 author: “techlead” citation: “wiki-decisions-pg-vs-mysql” tags: [database, architecture, decision] related_tickets: [“TICKET-012”] --- **上下文** 项目初期需要选择关系型数据库我们在PostgreSQL和MySQL之间进行了评估。 **权衡分析** - **PostgreSQL优势**JSONB支持更好对复杂查询和地理空间数据支持更成熟许可协议更宽松类BSD。 - **MySQL优势**在某些简单读写场景下性能略有优势生态工具略多。 **决策** 选择PostgreSQL因为我们对未来可能使用JSON字段和GIS功能有预期且其许可协议更符合项目开源策略。当AI在编写代码或讨论方案时它可以明确地说“根据我们的架构决策wiki-decisions-pg-vs-mysql这里使用JSONB字段是合理的。” 这种精确引用极大提升了沟通和决策的连续性。AI如何参与维护你可以直接要求AI助手“将我们刚才关于错误处理策略的讨论总结成一条知识记录保存到.wiki/how-to/目录下。” 由于AI已经通过技能理解了.wiki/的结构和模板它能够生成格式正确、包含必要元数据的文件。task -d .wiki lint命令可以用于自动化检查所有wiki页面的格式是否符合规范。5. 高级配置与集成让规范融入开发生命周期基础用法已经能带来很大提升但要让agent-repo-kit的价值最大化需要将其深度集成到你的团队工作流和自动化管道中。5.1 自定义技术栈与检查规则初始化时使用的--profiles参数如go,typescript-react并不是固定的。你可以根据自己项目的需要创建或组合配置。agent-repo-kit的配置核心是.convention-engineering.json文件它定义了本仓库需要遵守的“契约”。你可以手动编辑这个文件来启用或禁用某些检查或者调整规则严格度。例如{ “version”: “1.0”, “profiles”: [“go”, “node”, “docker”], “rules”: { “tickets”: { “require_estimate”: true, “estimate_units”: “story_points” }, “wiki”: { “require_citation”: true, “broken_link_check”: “warning” }, “docs”: { “enforce_taxonomy”: true } } }然后运行ark audit命令它会根据这份契约对仓库进行扫描并生成一份带有评分的报告指出哪些地方做得好哪些地方需要改进。这个报告可以集成到CI中作为合并请求Pull Request的一道检查关卡。5.2 与CI/CD管道集成将task verify和ark audit加入你的CI脚本如GitHub Actions、GitLab CI可以确保每个提交都符合团队约定的AI协作规范。这是一个示例的GitHub Actions工作流片段name: Convention Compliance on: [push, pull_request] jobs: verify: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup ark run: | curl -sSL https://raw.githubusercontent.com/gh-xj/agent-repo-kit/main/install.sh | sh echo “$HOME/.local/bin” $GITHUB_PATH - name: Verify Conventions run: task verify - name: Audit Repository run: ark audit --format github-actions audit-report.md # 可以将报告作为PR评论发布这样任何破坏.tickets/结构、.wiki/格式或者未遵循文档分类的提交都会导致CI失败从自动化层面保障规范的执行。5.3 适配其他AI助手运行时目前官方提供了对claude-code和codex的适配器。如果你使用其他AI助手例如某些IDE插件理论上也可以集成。关键在于理解“技能”的接口。一个技能本质上是一个目录其中包含一个SKILL.md文件该文件用自然语言描述了该技能的功能、触发词和使用示例。agent-repo-kit的技能是“运行时无关”的存放在skills/目录下。适配器adapters/的工作就是将这些通用技能“安装”到特定运行时能识别的特定位置。如果你需要为其他工具创建适配器可以研究adapters/claude-code/的结构它主要包含一个manifest.json将通用技能映射到运行时特定的路径。然后你可以通过类似ark adapters link的命令或手动创建符号链接来完成安装。6. 实战经验与避坑指南在实际项目中推广和使用agent-repo-kit几个月后我积累了一些宝贵的经验教训这些是在官方文档里不会提到的。6.1 如何引导团队接受新的工作流最大的挑战往往不是技术而是习惯。直接要求团队从Jira/GitHub Issues切换到文件系统的.tickets/可能会遇到阻力。我的建议是渐进式采用并行运行期在初期不强制要求所有任务都进.tickets/。可以指定某个小型特性或Bug修复周期作为试点要求试点任务必须使用新流程。让团队成员尤其是对此持怀疑态度的成员亲自体验与AI协作的流畅感。突出AI增益向团队演示如何通过AI快速生成一个格式完美的任务描述如何询问“我接下来该做什么”时AI能直接列出open/目录下的任务并给出建议。这种即时、上下文感知的辅助能力是传统工具难以比拟的。降低使用门槛利用好task -d .tickets new命令或者为团队成员创建更简单的Shell别名。目标是让创建/移动一个任务比在Web界面操作更快。6.2 .tickets目录的维护与清理随着时间推移done/目录下的任务会越来越多。虽然按日期归档有帮助但长期来看可能需要清理策略。定期归档我通常在每个版本发布后将上个版本的所有done/任务打包压缩移出项目目录存档到长期存储如公司Wiki或归档仓库。然后在.tickets/中只保留最近两个迭代周期的任务保持轻量。谨慎删除任务文件是历史记录。即使归档也尽量不要删除。它们对于追溯某个功能的决策上下文、复盘迭代速度非常有价值。ark audit可以帮助检查是否有任务文件被意外删除或损坏。6.3 确保AI技能的正确加载与更新有时你会发现AI助手似乎“忘记”了如何与.tickets/交互。这通常是技能没有正确加载导致的。重启是关键安装新技能或更新后务必重启你的AI助手客户端。大多数运行时只在启动时扫描技能目录。检查技能路径如果重启无效可以手动检查技能是否安装到位。对于Claude Code查看~/.claude/skills/目录下是否有convention-engineering等目录。对于通过npx skills安装的也可以运行npx skills ls -g来列表。技能冲突如果你手动修改过~/.claude/skills/下的文件或者安装了其他第三方技能可能存在冲突。最干净的方法是使用npx skills remove移除后重新安装。6.4 处理复杂任务的依赖关系.tickets/中任务文件的Frontmatter支持requires依赖和blocks阻塞字段这可以用来描述简单依赖。但对于非常复杂的、图状依赖的任务流仅靠文件系统会显得吃力。我的经验是将agent-repo-kit视为“执行层”的追踪而非“规划层”。复杂的项目规划、资源调度、甘特图仍然适合在更专业的项目管理工具中进行。你可以将那个工具中的“史诗”或“用户故事”拆解成具体的、可技术执行的“任务”再导入或手动创建到.tickets/中。这样.tickets/始终保持轻量和面向具体开发动作。7. 常见问题排查与解决方案实录在实际操作中你可能会遇到一些具体的问题。以下是我遇到过的典型问题及其解决方法。问题一运行ark init时提示“command not found: task”。原因ark init会生成一个Taskfile.yml而后续的task verify命令依赖于 Go Task 这个任务运行器。解决安装Go Task。通常可以通过包管理器快速安装# macOS (Homebrew) brew install go-task # Linux (使用官方脚本) sh -c “$(curl --location https://taskfile.dev/install.sh)” -- -d -b ~/.local/bin # 安装后确认task --version可以运行。问题二AI助手无法识别新创建的任务或wiki页面。原因1AI助手的上下文可能没有包含最新的文件变更。某些助手在长时间会话后文件系统感知会“滞后”。解决1尝试在对话中明确指示AI“重新读取.tickets/open/目录的内容”或者直接开启一个新的聊天会话。原因2任务或wiki文件的Frontmatter格式错误如YAML缩进不对、缺少必需字段。解决2运行task -d .tickets test和task -d .wiki lint来检查格式。AI技能依赖于正确的格式来解析信息。问题三npx skills add命令执行失败报网络或权限错误。原因npx会从npm registry下载skills这个包可能需要代理或特定权限。解决检查网络连接。尝试使用npm install -g agent-tooling/skills全局安装skills命令行工具然后再运行skills add ...命令。如果是在企业内网可能需要配置npm代理。问题四我想自定义任务模板或wiki模板该怎么做解决agent-repo-kit在.tickets/_templates/和.wiki/_templates/目录下提供了默认模板。你可以直接修改这些目录下的*.md文件。例如在.tickets/_templates/ticket.md中你可以为你的团队添加固定的“代码审查人”字段或“测试用例”部分。修改后后续通过task -d .tickets new创建的任务就会使用你的自定义模板。问题五如何将现有的GitHub Issues迁移到.tickets/解决目前没有官方的一键迁移工具。我采用的半自动化方法是使用GitHub API或gh命令行工具导出Issues为JSON。写一个简单的脚本Python/Node.js读取JSON按照agent-repo-kit的任务文件格式Frontmatter Markdown正文生成对应的.md文件并放入.tickets/open/目录。对于已关闭的Issue可以放入.tickets/done/日期/目录。 这个过程虽然需要一些脚本编写但通常是一次性的并且能让你自定义映射规则如将Issue标签映射为任务标签。