Back to Details

doc-driven-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

文档驱动开发规范

Documentation-Driven Development Specification

在生成代码或修复 bug 时，先看官方文档与示例，再动手实现。
When generating code or fixing bugs, consult official documentation and examples first before starting implementation.

⚠️ 核心强制要求

⚠️ Core Mandatory Requirements

必须查文档的场景

Scenarios Where Documentation Must Be Consulted

  • 落地新功能、接第三方库 API、或排查 API 报错时，先查官方文档
  • 遇到 
    AttributeError
    / 
    TypeError
    / 版本变更不确定时，必须验证 API 定义与示例
  • 对项目自带封装的内部 API，可酌情跳过
  • When implementing new features, connecting to third-party library APIs, or troubleshooting API errors, consult official documentation first
  • When encountering 
    AttributeError
    / 
    TypeError
    / uncertain version changes, must verify API definitions and examples
  • For internal APIs encapsulated by the project itself, you can skip as appropriate

Agent 执行步骤

Agent Execution Steps

  1. 停止猜测：明确要查的 API/模块名称和版本
  2. 查阅文档：优先使用 
    Context7
    获取官方文档；若不可用再用 
    DuckDuckGo
    搜索官方来源并二次核验
  3. 基于文档实现：依据文档的参数、返回值和示例实现或修复代码
  1. Stop guessing: Clarify the name and version of the API/module to be queried
  2. Consult documentation: Prioritize using 
    Context7
    to obtain official documentation; if unavailable, use 
    DuckDuckGo
    to search for official sources and conduct secondary verification
  3. Implement based on documentation: Implement or fix code according to the parameters, return values and examples in the documentation

MCP 调用基线（文档查阅场景）

MCP Invocation Baseline (Documentation Query Scenarios)

  • 文档/API 问题优先使用 
    Context7
    ，最新公告或入口信息再使用 
    DuckDuckGo
  • 单轮最多调用一种外部服务；确需多工具时串行并说明理由
  • 查询保持最小必要（关键词、结果数、时间窗、tokens）
  • 发生 429/限流时，退避 20 秒并缩小范围后重试
  • 输出中附“工具调用简报”（工具、输入摘要、参数、时间、来源、重试）
  • 默认离线优先，不上传敏感信息，遵守 robots/ToS 与隐私约束
  • For documentation/API issues, prioritize using 
    Context7
    , and use 
    DuckDuckGo
    for latest announcements or entry information
  • Call at most one external service per round; if multiple tools are really needed, call them serially and explain the reasons
  • Keep queries as minimal and necessary as possible (keywords, number of results, time window, tokens)
  • When 429/rate limiting occurs, back off for 20 seconds and narrow the scope before retrying
  • Attach "Tool Call Briefing" in the output (tool, input summary, parameters, time, source, retry)
  • Offline first by default, do not upload sensitive information, comply with robots/ToS and privacy constraints

AI Agent 行为要求

AI Agent Behavior Requirements

问题识别

Problem Identification

问题类型特征处理方式
API 不存在
AttributeError: 'X' has no attribute 'Y'
查找正确的 API
参数错误
TypeError: unexpected keyword argument
查找正确的参数
行为异常结果不符合预期查找正确的用法
版本问题某版本后 API 变更查找版本差异
Problem TypeFeatureHandling Method
API does not exist
AttributeError: 'X' has no attribute 'Y'
Find the correct API
Parameter error
TypeError: unexpected keyword argument
Find the correct parameters
Abnormal behaviorResults do not meet expectationsFind the correct usage
Version issueAPI changed after a certain versionFind version differences

收集错误信息

Collect Error Information

必须收集：
  • 完整的错误堆栈
  • 相关代码片段
  • 使用的库/框架版本
Must collect:
  • Complete error stack
  • Relevant code snippets
  • Version of the library/framework used

基于文档实现（禁止猜测）

Implement Based on Documentation (Guessing is Prohibited)

python
undefined
python
undefined

错误：基于猜测实现

错误：基于猜测实现

index.query(question, top_k=10) # 可能参数名不对
index.query(question, top_k=10) # 可能参数名不对

正确：基于文档实现

正确：基于文档实现

查阅文档后确认正确的参数名

查阅文档后确认正确的参数名

index.query(question, similarity_top_k=10)
undefined
index.query(question, similarity_top_k=10)
undefined

修复后验证

Verification After Fix

  • 运行测试确认修复
  • 检查是否引入新问题
  • 验证在不同场景下的表现
  • Run tests to confirm the fix
  • Check if new problems are introduced
  • Verify performance in different scenarios

参考资料

References

  • references/api-verification.md
    - API 验证流程详细说明（问题识别、文档查阅、实施修复）
  • references/search-strategy.md
    - 文档搜索策略与提问指引
  • references/mcp-usage-rules.md
    - MCP 调用规则（工具选择、速率限制、安全边界、失败降级与可追溯输出）
  • references/api-verification.md
    - Detailed description of API verification process (problem identification, documentation consultation, implementation of fixes)
  • references/search-strategy.md
    - Documentation search strategy and question guidance
  • references/mcp-usage-rules.md
    - MCP invocation rules (tool selection, rate limiting, security boundary, failure degradation and traceable output)