agent-repo-kit：AI辅助开发的仓库规范工具包

agent-repo-kit提供了一套与AI工具无关的仓库约定和工具集，支持工单管理、知识库组织和审计工作流，兼容Claude Code、Codex、Cursor等多种AI编程助手。

随着Claude Code、GitHub Copilot、Cursor等AI编程助手的普及，开发者逐渐发现一个新问题：如何让AI更好地理解和融入既有项目的上下文？不同AI工具各有特色，但项目知识的管理方式却往往碎片化——有的信息在README里，有的在issue里，有的只在核心开发者的脑海中。

agent-repo-kit试图解决这一痛点。它提供了一套"与工具无关"的仓库约定，无论团队使用哪种AI助手（甚至同时使用多种），都能通过统一的规范让AI快速理解项目结构、工作流和决策历史。

工具包的设计遵循几个关键原则：

本地优先：所有工作追踪和知识管理都以本地文件形式存在，不依赖外部服务。即使离线，项目的历史记录和上下文依然完整可用。

工具无关：约定本身是中立的，不绑定任何特定的AI工具。通过适配器层，相同的规范可以同时服务于Claude Code、Codex、Cursor等不同运行时。

渐进采用：团队可以按需采纳工具包的不同部分，从简单的工单追踪开始，逐步扩展到完整的知识库和审计工作流。

可验证性：工具包包含评分机制，可以量化评估一个仓库对这些约定的采纳程度，帮助团队识别改进空间。

这是工具包的核心创新之一。.work/目录作为项目本地的"轻量级事务系统"，包含：

• 收件箱（inbox）：快速捕获新想法、待办事项或发现的问题
• 分类队列（triage）：对待处理事项进行优先级和类别划分
• 视图（views）：按不同维度（如按状态、按负责人、按里程碑）组织工作项
• JSON原生CLI：通过work命令行工具进行查询和操作，便于脚本化和AI集成

这种设计的巧妙之处在于，它将项目管理的最小可行集直接嵌入代码仓库，既保持了与代码的版本同步，又避免了外部项目管理工具的上下文切换成本。

工具包提供了一套"convention-evaluator"技能，可以对新仓库或既有仓库进行扫描，评估其对约定的采纳程度，并生成带有具体改进建议的分级报告。这对于以下场景特别有价值：

• 新成员快速了解项目规范程度
• 技术负责人识别知识管理盲点
• 引入AI助手前评估项目准备度

工具包内置了多个可复用的"技能"，每个技能都是针对特定场景的约定集合：

• convention-engineering：仓库约定、文档结构、技术栈配置
• skill-builder：创建、重构和审计其他技能的方法论
• taskfile-authoring：编写规范Taskfile的指南
• attack-architecture：对抗性架构审查流程
• harness-router：学习成果和工具改进的路由决策框架

这些技能以纯文本形式存在，不依赖特定工具，可以被任何AI助手读取和应用。

对于需要维护大量知识性内容的项目，工具包提供了可选的.wiki/目录结构，用于组织与代码库紧密关联的文档，如架构决策记录（ADR）、操作手册、设计文档等。

工具包提供了多种安装方式：

通过npx安装技能（需要Node.js）：

npx skills add gh-xj/agent-repo-kit -g -a claude-code -a codex --skill '*' -y

通过install.sh安装二进制工具：

curl -sSL https://raw.githubusercontent.com/gh-xj/agent-repo-kit/main/install.sh | sh

初始化新项目：

ark init --repo-root /path/to/your-repo --profiles go,typescript-react

初始化后，项目即具备task verify能力，可以运行约定检查和work视图查询。