1- # AGENTS.md
1+ ## Issue Tracking with bd (beads)
22
3- ## 使用 bd (beads) 进行 Issue 跟踪
3+ ** IMPORTANT ** : This project uses ** bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
44
5- ** 重要提示 ** : 本项目使用 ** bd (beads) ** 进行 ** 所有 ** issue 跟踪。不要使用 markdown TODO 列表、任务清单或其他跟踪方式。
5+ ### Why bd?
66
7- ### 为什么使用 bd?
7+ - Dependency-aware: Track blockers and relationships between issues
8+ - Git-friendly: Auto-syncs to JSONL for version control
9+ - Agent-optimized: JSON output, ready work detection, discovered-from links
10+ - Prevents duplicate tracking systems and confusion
811
9- - ** 依赖感知** : 跟踪 issue 之间的阻塞关系和关联
10- - ** Git 友好** : 自动同步到 JSONL,便于版本控制
11- - ** 为 Agent 优化** : JSON 输出、就绪工作检测、discovered-from 链接
12- - ** 防止重复** : 避免多个跟踪系统造成的混乱
12+ ### Quick Start
1313
14- ### 快速开始
15-
16- ** 查看就绪任务:**
14+ ** Check for ready work:**
1715``` bash
1816bd ready --json
1917```
2018
21- ** 创建新 issue :**
19+ ** Create new issues :**
2220``` bash
23- bd create " Issue 标题 " -t bug| feature| task -p 0-4 --json
24- bd create " Issue 标题 " -p 1 --deps discovered-from:bd-123 --json
21+ bd create " Issue title " -t bug| feature| task -p 0-4 --json
22+ bd create " Issue title " -p 1 --deps discovered-from:bd-123 --json
2523```
2624
27- ** 认领和更新 :**
25+ ** Claim and update :**
2826``` bash
2927bd update bd-42 --status in_progress --json
3028bd update bd-42 --priority 1 --json
3129```
3230
33- ** 完成任务 :**
31+ ** Complete work :**
3432``` bash
35- bd close bd-42 --reason " 已完成 " --json
33+ bd close bd-42 --reason " Completed " --json
3634```
3735
38- ### Issue 类型
36+ ### Issue Types
37+
38+ - ` bug ` - Something broken
39+ - ` feature ` - New functionality
40+ - ` task ` - Work item (tests, docs, refactoring)
41+ - ` epic ` - Large feature with subtasks
42+ - ` chore ` - Maintenance (dependencies, tooling)
43+
44+ ### Priorities
3945
40- - ` bug ` - 某些东西坏了
41- - ` feature ` - 新功能
42- - ` task ` - 工作项(测试、文档、重构)
43- - ` epic ` - 大型功能,包含子任务
44- - ` chore ` - 维护工作(依赖、工具)
46+ - ` 0 ` - Critical (security, data loss, broken builds)
47+ - ` 1 ` - High (major features, important bugs)
48+ - ` 2 ` - Medium (default, nice-to-have)
49+ - ` 3 ` - Low (polish, optimization)
50+ - ` 4 ` - Backlog (future ideas)
4551
46- ### 优先级
52+ ### Workflow for AI Agents
4753
48- - ` 0 ` - 紧急(安全、数据丢失、构建失败)
49- - ` 1 ` - 高(主要功能、重要 bug)
50- - ` 2 ` - 中(默认,不错但非必需)
51- - ` 3 ` - 低(优化、润色)
52- - ` 4 ` - 待办(未来想法)
54+ 1 . ** Check ready work** : ` bd ready ` shows unblocked issues
55+ 2 . ** Claim your task** : ` bd update <id> --status in_progress `
56+ 3 . ** Work on it** : Implement, test, document
57+ 4 . ** Discover new work?** Create linked issue:
58+ - ` bd create "Found bug" -p 1 --deps discovered-from:<parent-id> `
59+ 5 . ** Complete** : ` bd close <id> --reason "Done" `
60+ 6 . ** Commit together** : Always commit the ` .beads/issues.jsonl ` file together with the code changes so issue state stays in sync with code state
5361
54- ### AI Agent 工作流程
62+ ### Auto-Sync
5563
56- 1 . ** 检查就绪工作** : ` bd ready ` 显示未阻塞的 issues
57- 2 . ** 认领任务** : ` bd update <id> --status in_progress `
58- 3 . ** 开始工作** : 实现、测试、编写文档
59- 4 . ** 发现新工作?** 创建关联 issue:
60- - ` bd create "发现的 bug" -p 1 --deps discovered-from:<parent-id> `
61- 5 . ** 完成** : ` bd close <id> --reason "完成" `
62- 6 . ** 一并提交** : 务必将 ` .beads/issues.jsonl ` 文件与代码更改一起提交,以保持 issue 状态与代码状态同步
64+ bd automatically syncs with git:
65+ - Exports to ` .beads/issues.jsonl ` after changes (5s debounce)
66+ - Imports from JSONL when newer (e.g., after ` git pull ` )
67+ - No manual export/import needed!
6368
64- ### 自动同步
69+ ### GitHub Copilot Integration
6570
66- bd 自动与 git 同步:
67- - 更改后导出到 ` .beads/issues.jsonl ` (5秒防抖)
68- - 当 JSONL 较新时自动导入(例如 ` git pull ` 后)
69- - 无需手动导出/导入!
71+ If using GitHub Copilot, also create ` .github/copilot-instructions.md ` for automatic instruction loading.
72+ Run ` bd onboard ` to get the content, or see step 2 of the onboard instructions.
7073
71- ### MCP Server (推荐 )
74+ ### MCP Server (Recommended )
7275
73- 如果使用 Claude 或兼容 MCP 的客户端,请安装 beads MCP server:
76+ If using Claude or MCP-compatible clients, install the beads MCP server:
7477
7578``` bash
7679pip install beads-mcp
7780```
7881
79- 添加到 MCP 配置(例如 ` ~/.config/claude/config.json ` ) :
82+ Add to MCP config (e.g., ` ~/.config/claude/config.json ` ) :
8083``` json
8184{
8285 "beads" : {
@@ -86,92 +89,46 @@ pip install beads-mcp
8689}
8790```
8891
89- 然后使用 ` mcp__beads__* ` 函数代替 CLI 命令。
92+ Then use ` mcp__beads__* ` functions instead of CLI commands.
9093
91- ### 管理 AI 生成的规划文档
94+ ### Managing AI-Generated Planning Documents
9295
93- AI 助手在开发过程中经常创建规划和设计文档 :
96+ AI assistants often create planning and design documents during development :
9497- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
9598- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
96- - TESTING_GUIDE.md, TECHNICAL_DESIGN.md 等类似文件
99+ - TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
97100
98- ** 最佳实践: 使用专用目录存放这些临时文件 **
101+ ** Best Practice: Use a dedicated directory for these ephemeral files **
99102
100- ** 推荐做法 :**
101- - 在项目根目录创建 ` history/ ` 目录
102- - 将所有 AI 生成的规划/设计文档存放在 ` history/ `
103- - 保持仓库根目录整洁,专注于永久项目文件
104- - 仅在明确要求审查过去规划时才访问 ` history/ `
103+ ** Recommended approach :**
104+ - Create a ` history/ ` directory in the project root
105+ - Store ALL AI-generated planning/design docs in ` history/ `
106+ - Keep the repository root clean and focused on permanent project files
107+ - Only access ` history/ ` when explicitly asked to review past planning
105108
106- ** .gitignore 示例条目(可选) ** :
109+ ** Example .gitignore entry (optional): **
107110```
108- # AI 规划文档(临时)
111+ # AI planning documents (ephemeral)
109112history/
110113```
111114
112- ** 好处:**
113- - ✅ 仓库根目录整洁
114- - ✅ 临时文档和永久文档清晰分离
115- - ✅ 可根据需要轻松排除版本控制
116- - ✅ 保留规划历史,便于追溯
117- - ✅ 浏览项目时减少干扰
118-
119- ### 重要规则
120-
121- - ✅ ** 所有** 任务跟踪都使用 bd
122- - ✅ 程序化使用时始终使用 --json 标志
123- - ✅ 使用 ` discovered-from ` 依赖链接发现的工作
124- - ✅ 在问"我该做什么"之前先检查 ` bd ready `
125- - ✅ 将 AI 规划文档存放在 ` history/ ` 目录
126- - ❌ 不要创建 markdown TODO 列表
127- - ❌ 不要使用外部 issue 跟踪器
128- - ❌ 不要重复跟踪系统
129- - ❌ 不要用规划文档 clutter 仓库根目录
130-
131- 更多详情,请查看 README.md 和 QUICKSTART.md.
132-
133- ## Build、Lint 和 Test 命令
134-
135- - ** 构建:**
136- ` bun run build ` (使用 tsup)
137- - ** 开发:**
138- ` bun run dev `
139- - ** Lint:**
140- ` bun run lint ` (使用 @echristian/eslint-config )
141- - ** Lint & 修复暂存文件:**
142- ` bunx lint-staged `
143- - ** 测试所有:**
144- ` bun test `
145- - ** 测试单个文件:**
146- ` bun test tests/claude-request.test.ts `
147- - ** 启动(生产):**
148- ` bun run start `
149-
150- ## 代码风格指南
151-
152- - ** 导入:**
153- 使用 ESNext 语法。优先使用 ` ~/* ` 绝对导入 ` src/* ` (见 ` tsconfig.json ` )
154- - ** 格式化:**
155- 遵循 Prettier (含 ` prettier-plugin-packagejson ` )。运行 ` bun run lint ` 自动修复
156- - ** 类型:**
157- 严格 TypeScript (` strict: true ` )。避免 ` any ` ;使用显式类型和接口
158- - ** 命名:**
159- 变量/函数使用 ` camelCase ` ,类型/类使用 ` PascalCase `
160- - ** 错误处理:**
161- 使用显式错误类 (见 ` src/lib/error.ts ` )。避免静默失败
162- - ** 未使用:**
163- 未使用的导入/变量是错误 (` noUnusedLocals ` , ` noUnusedParameters ` )
164- - ** Switch:**
165- switch 语句不允许 fallthrough
166- - ** 模块:**
167- 使用 ESNext 模块,不使用 CommonJS
168- - ** 测试:**
169- 使用 Bun 内置测试运行器。测试放在 ` tests/ ` ,命名为 ` *.test.ts `
170- - ** Lint:**
171- 使用 ` @echristian/eslint-config ` (见 npm 详情)。包含风格、未使用导入、正则和 package.json 规则
172- - ** 路径:**
173- 从 ` src/ ` 导入使用路径别名 (` ~/* ` )
174-
175- ---
176-
177- 此文件专为 agentic coding agents 定制。更多详情,见 ` eslint.config.js ` 和 ` tsconfig.json ` 中的配置。未检测到 Cursor 或 Copilot 规则。
115+ ** Benefits:**
116+ - ✅ Clean repository root
117+ - ✅ Clear separation between ephemeral and permanent documentation
118+ - ✅ Easy to exclude from version control if desired
119+ - ✅ Preserves planning history for archeological research
120+ - ✅ Reduces noise when browsing the project
121+
122+ ### Important Rules
123+
124+ - ✅ Use bd for ALL task tracking
125+ - ✅ Always use ` --json ` flag for programmatic use
126+ - ✅ Link discovered work with ` discovered-from ` dependencies
127+ - ✅ Check ` bd ready ` before asking "what should I work on?"
128+ - ✅ Store AI planning docs in ` history/ ` directory
129+ - ❌ Do NOT create markdown TODO lists
130+ - ❌ Do NOT use external issue trackers
131+ - ❌ Do NOT duplicate tracking systems
132+ - ❌ Do NOT clutter repo root with planning documents
133+
134+ For more details, see README.md and QUICKSTART.md.
0 commit comments