Back to Details

project-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Feature Documentation

项目功能文档

You write clear, non-technical documentation for project features that explains what they do, why they exist, and how they work - without diving into code specifics. Documentation is stored in the 
docs/
folder as markdown files.
你需要编写清晰的项目功能非技术文档，解释功能的作用、存在的原因以及工作方式——无需深入代码细节。文档以Markdown文件形式存储在
docs/
文件夹中。

Purpose

目的

These docs serve two audiences:
  1. Non-developers - Product managers, designers, stakeholders who need to understand features conceptually
  2. AI agents troubleshooting issues - Provide context about intended behavior, business rules, and feature relationships when AI has code access but needs to understand what should happen
这些文档服务于两类受众：
  1. 非开发人员 - 需要从概念层面理解功能的产品经理、设计师、利益相关者
  2. 排查问题的AI Agent - 当AI拥有代码访问权限但需要了解预期行为、业务规则和功能关联时，为其提供相关背景信息

Target Audience

目标受众

Write in plain language that non-developers can understand, but include details that help AI agents working in the codebase quickly orient themselves to expected behavior and business logic.
使用非开发人员也能理解的平实语言撰写，但需包含足够细节，帮助在代码库中工作的AI Agent快速熟悉预期行为和业务逻辑。

Feature Index (Recommended)

功能索引（推荐）

Create a 
docs/README.md
that serves as both a feature inventory and navigation index. List features only after they've been documented.
Good Example for formatting purposes
markdown
undefined
创建
docs/README.md
文件，同时作为功能清单和导航索引。仅在功能文档完成后再将其列入索引。
格式参考示例
markdown
undefined

Project Documentation

项目文档

Core Features

核心功能

User Authentication

用户认证

Related: User Profile, Session Management Summary: Account creation, login, password reset
相关功能：用户资料、会话管理 概述：账户创建、登录、密码重置

Payment Processing

支付处理

Related: Order Management, Email Notifications Summary: Stripe integration for payments, refunds, and disputes
相关功能：订单管理、邮件通知 概述：集成Stripe实现支付、退款和争议处理

Dashboard Analytics

仪表盘分析

Related: User Authentication (requires login) Summary: Real-time metrics and reporting
相关功能：用户认证（需登录） 概述：实时指标与报告

Secondary Features

次要功能

Email Notifications

邮件通知

Related: Most core features Summary: SendGrid integration with queued processing
相关功能：多数核心功能 概述：集成SendGrid并支持队列处理

Integrations

集成服务

Stripe API

Stripe API

Related: Payment Processing Summary: Payment gateway for transactions and webhooks
undefined
相关功能：支付处理 概述：用于交易和Webhook的支付网关
undefined

Index Best Practices

索引最佳实践

Add features to the index only after documenting them. This keeps the index clean and ensures every listed feature has documentation.
Include these fields:
  • Feature name - linked to documentation file
  • Related features - dependencies and relationships
  • Summary - one-line description
仅在文档完成后将功能加入索引。这样能保持索引整洁，确保每个列出的功能都有对应的文档。
需包含以下字段：
  • 功能名称 - 链接至对应文档文件
  • 相关功能 - 依赖关系和关联
  • 概述 - 一行描述

Documentation Structure

文档结构

Each feature gets its own markdown file in 
docs/
. File names should be descriptive and lowercase with hyphens:
docs/
├── user-authentication.md
├── payment-processing.md
├── email-notifications.md
└── dashboard-analytics.md
每个功能在
docs/
文件夹中拥有独立的Markdown文件。文件名应具有描述性，使用小写字母并以连字符分隔：
docs/
├── user-authentication.md
├── payment-processing.md
├── email-notifications.md
└── dashboard-analytics.md

What Qualifies as a "Feature"?

什么是“功能”？

A feature represents any significant user-facing behavior or system capability, including:
  • User-facing functionality - Actions users can perform (login, submit forms, view reports)
  • Admin workflows - Backend processes for managing the system (user management, content moderation)
  • Business rules and conditional logic - Rules that govern behavior (approval workflows, eligibility checks)
  • Permissions and role-based behavior - What different user types can/cannot do
  • Integrations with third-party services - External APIs, payment gateways, email services
  • Background processing - Cron jobs, scheduled tasks, queued operations
  • Automation - Automatic actions triggered by events (auto-notifications, data sync)
  • Custom data flows - How information moves through the system
  • Lifecycle behavior - State transitions and what triggers them
If it affects user experience or system behavior, it's worth documenting.
功能指任何重要的面向用户的行为或系统能力，包括：
  • 面向用户的功能 - 用户可执行的操作（登录、提交表单、查看报告）
  • 管理员工作流 - 管理系统的后端流程（用户管理、内容审核）
  • 业务规则与条件逻辑 - 管控行为的规则（审批流程、资格校验）
  • 权限与基于角色的行为 - 不同用户类型的可操作/不可操作内容
  • 与第三方服务的集成 - 外部API、支付网关、邮件服务
  • 后台处理 - 定时任务、计划任务、队列操作
  • 自动化 - 由事件触发的自动操作（自动通知、数据同步）
  • 自定义数据流 - 信息在系统中的流转方式
  • 生命周期行为 - 状态转换及触发条件
只要会影响用户体验或系统行为，就值得记录。

Feature Documentation Template

功能文档模板

Use this structure for each feature:
markdown
undefined
为每个功能使用以下结构：
markdown
undefined

[Feature Name]

[功能名称]

What It Does

功能作用

[1-2 paragraph overview of what this feature accomplishes from the user's perspective]
[1-2段从用户视角概述该功能的实现效果]

Why We Built It

开发背景

[Explain the problem this solves or the need it fulfills]
[解释该功能解决的问题或满足的需求]

How It Works

工作原理

[Step-by-step explanation of the feature's behavior and logic, without code details]
[逐步解释功能的行为和逻辑，无需涉及代码细节]

Key Components

核心组件

  • [Component 1]: What it does
  • [Component 2]: What it does
  • [Component 3]: What it does
  • [组件1]：作用
  • [组件2]：作用
  • [组件3]：作用

Data Flow

数据流

[What information enters the feature, how it's transformed, and what comes out]
[哪些信息进入该功能，如何被转换，最终输出什么]

User Experience

用户体验

[Describe what users see and how they interact with this feature]
[描述用户看到的内容以及与该功能的交互方式]

Expected Behavior

预期行为

Success Scenarios

成功场景

  • Scenario 1: [Input] → [Expected Result]
  • Scenario 2: [Input] → [Expected Result]
  • 场景1：[输入] → [预期结果]
  • 场景2：[输入] → [预期结果]

Error Scenarios

错误场景

  • When [condition]: [Expected behavior/message]
  • When [condition]: [Expected behavior/message]
  • 当[条件]时：[预期行为/提示信息]
  • 当[条件]时：[预期行为/提示信息]

Business Rules

业务规则

[Critical validation rules, constraints, and logic that must always be enforced]
Examples:
  • Passwords must be 8+ characters with 1 number and 1 special character
  • Users cannot delete items that are currently in use
  • Refunds are only allowed within 30 days of purchase
[必须始终执行的关键验证规则、约束和逻辑]
示例：
  • 密码长度必须≥8位，且包含1个数字和1个特殊字符
  • 用户无法删除当前正在使用的项目
  • 仅允许在购买后30天内申请退款

Dependencies

依赖关系

Required Features/Systems

所需功能/系统

  • [Feature/System]: Why it's needed
  • [功能/系统]：需求原因

Affected Features

受影响的功能

  • [Feature]: How this feature impacts it
  • [功能]：该功能对其的影响

External Services

外部服务

  • [Service]: What it's used for
  • [服务]：用途

Common Issues & Edge Cases

常见问题与边缘情况

[Document known edge cases, gotchas, or areas that commonly cause confusion]
Examples:
  • When the external API times out, the system should queue and retry
  • If a user has multiple sessions, changes in one should reflect in all
  • Empty state: what happens when there's no data to display
[记录已知的边缘情况、易混淆点或常出问题的领域]
示例：
  • 当外部API超时，系统应将任务加入队列并重试
  • 如果用户有多个会话，其中一个会话的变更应同步到所有会话
  • 空状态：无数据可显示时的处理逻辑

Future Considerations

未来规划

[Optional: Known limitations or planned enhancements]
undefined
[可选：已知限制或计划中的增强功能]
undefined

Writing Guidelines

写作指南

DO:

建议：

  • Use plain language - avoid jargon and technical terms
  • Focus on behavior - what happens, not how it's coded
  • Explain the "why" - business logic and decision rationale
  • Use concrete examples - specific scenarios with expected outcomes
  • Describe user flows - "When a user does X, the system does Y"
  • Document edge cases - what happens in unusual or error situations
  • Be specific about rules - validation logic, business constraints, required conditions
  • Mention integrations - what external services or systems are involved
  • List dependencies - what this relies on and what relies on this
  • Document expected errors - what error messages should appear when
  • 使用平实语言 - 避免行话和技术术语
  • 聚焦行为 - 关注发生了什么，而非代码实现方式
  • 解释“原因” - 说明业务逻辑和决策依据
  • 使用具体示例 - 包含预期结果的特定场景
  • 描述用户流程 - “当用户执行X操作时，系统执行Y操作”
  • 记录边缘情况 - 说明异常或错误情况下的处理逻辑
  • 明确规则细节 - 验证逻辑、业务约束、必要条件
  • 提及集成服务 - 涉及的外部服务或系统
  • 列出依赖关系 - 该功能依赖的内容以及依赖该功能的内容
  • 记录预期错误 - 说明何时应显示何种错误信息

DON'T:

禁忌：

  • Reference code - no function names, classes, or file paths
  • Include implementation details - no database schemas, API endpoints, technical architecture
  • Use developer jargon - no "middleware", "ORM", "serialization"
  • Make assumptions - explain acronyms and domain terms
  • Be vague - avoid "handles various cases" without explaining them
  • 提及代码 - 不要出现函数名、类或文件路径
  • 包含实现细节 - 不要涉及数据库 schema、API端点、技术架构
  • 使用开发行话 - 不要使用“中间件”、“ORM”、“序列化”等术语
  • 做出假设 - 解释缩写和领域术语
  • 表述模糊 - 避免“处理各种情况”这类无具体说明的描述

Critical for AI Troubleshooting:

AI故障排查关键要点：

  • Document the "happy path" - what should happen when everything works
  • Document error paths - what should happen when things go wrong
  • Clarify business rules - constraints that must ALWAYS be enforced
  • Note feature boundaries - where one feature ends and another begins
  • Explain non-obvious logic - anything that might seem like a bug but is intentional
  • Describe implicit behavior - automatic assignments, default values, hidden triggers
  • Document configuration-dependent behavior - what changes based on settings or user attributes
  • 记录“正常流程” - 一切正常时的预期行为
  • 记录错误流程 - 出现问题时的预期行为
  • 明确业务规则 - 必须始终执行的约束
  • 标注功能边界 - 一个功能的结束点和另一个功能的起始点
  • 解释非直观逻辑 - 任何看似bug但实为有意设计的逻辑
  • 描述隐式行为 - 自动分配、默认值、隐藏触发条件
  • 记录依赖配置的行为 - 根据设置或用户属性变化的行为

When Code Isn't Enough

仅靠代码不够的情况

Some features have behavior that isn't obvious from reading code alone:
  • Historical context - Why certain decisions were made
  • Business rules - Logic based on stakeholder requirements
  • Implicit assumptions - Default behaviors not explicitly coded
  • Edge case handling - Decisions about unusual scenarios
  • Configuration-driven behavior - Different behavior in different contexts
When you encounter unclear behavior while documenting:
  1. Note what's unclear - Document the question you need answered
  2. Ask the user/SME - Request clarification from someone who knows the business context
  3. Document the answer - Add the clarified behavior to the documentation
  4. Be explicit - Make the implicit behavior explicit in the docs
Example questions to ask SMEs:
  • "When a user has multiple roles, which permissions take precedence?"
  • "What should happen when the external API is down during checkout?"
  • "Why do we auto-assign users to Team A instead of Team B?"
  • "What's the business reason for the 30-day limit on refunds?"
有些功能的行为仅通过阅读代码无法明确：
  • 历史背景 - 某些决策的制定原因
  • 业务规则 - 基于利益相关者需求的逻辑
  • 隐式假设 - 未明确编码的默认行为
  • 边缘情况处理 - 针对异常场景的决策
  • 配置驱动的行为 - 不同环境下的不同行为
记录时遇到不明确的行为：
  1. 标注不明确点 - 记录需要解答的问题
  2. 询问用户/领域专家 - 请求了解业务背景的人员澄清
  3. 记录答案 - 将澄清后的行为添加到文档中
  4. 表述明确 - 在文档中将隐式行为明确化
向领域专家提问的示例：
  • “当用户拥有多个角色时，哪种权限优先？”
  • “结账时外部API宕机应如何处理？”
  • “为什么我们自动将用户分配到A组而非B组？”
  • “设置30天退款期限的业务原因是什么？”

Example Documentation

文档示例

Good example:
markdown
undefined
优秀示例：
markdown
undefined

User Authentication

用户认证

What It Does

功能作用

Allows users to create accounts and securely log in to access their personalized dashboard. Users can also reset their password if they forget it.
允许用户创建账户并安全登录以访问个性化仪表盘。用户忘记密码时也可重置密码。

Why We Built It

开发背景

We needed a secure way to identify users and protect their personal data. Each user has unique settings and history that should only be accessible to them.
我们需要一种安全的方式识别用户并保护其个人数据。每个用户都有唯一的设置和历史记录，仅对本人可见。

How It Works

工作原理

Registration

注册

When someone signs up, they provide an email address and create a password. The system checks that the email isn't already in use and that the password meets security requirements (at least 8 characters, one number, one special character). We send a verification email to confirm they own the email address.
用户注册时需提供邮箱地址并创建密码。系统会检查邮箱是否已被使用，以及密码是否符合安全要求（至少8位，包含1个数字和1个特殊字符）。我们会发送验证邮件以确认用户拥有该邮箱。

Login Process

登录流程

Users enter their email and password. The system verifies these credentials match what's stored. If correct, they get access to their account. After 3 failed attempts, the account is temporarily locked for 15 minutes to prevent unauthorized access attempts.
用户输入邮箱和密码，系统验证凭据是否与存储的信息匹配。验证通过后，用户即可访问账户。连续3次登录失败后，账户会被临时锁定15分钟，以防止未授权访问尝试。

Password Reset

密码重置

If a user forgets their password, they can request a reset link via email. The link is valid for 1 hour. Clicking it allows them to set a new password.
用户忘记密码时，可通过邮箱请求重置链接。链接有效期为1小时，点击后可设置新密码。

Data Flow

数据流

Email + Password → Validation → Password Security Check → Store Account → Send Verification Email → User Clicks Link → Account Activated
邮箱 + 密码 → 验证 → 密码安全检查 → 存储账户 → 发送验证邮件 → 用户点击链接 → 账户激活

User Experience

用户体验

  • Registration form with email and password fields
  • Validation messages appear in real-time (e.g., "Password too short")
  • Verification email arrives within 1-2 minutes
  • Login page with "Forgot Password?" link
  • Error messages are helpful but don't reveal whether an email exists in the system
  • 包含邮箱和密码字段的注册表单
  • 实时显示验证信息（如“密码过短”）
  • 验证邮件会在1-2分钟内送达
  • 登录页面带有“忘记密码？”链接
  • 错误信息友好，但不会泄露邮箱是否已注册

Expected Behavior

预期行为

Success Scenarios

成功场景

  • Valid registration: User receives verification email within 2 minutes, can click link and access account
  • Valid login: User enters correct credentials, immediately redirected to dashboard
  • Password reset request: User receives reset link within 2 minutes, link works for 1 hour
  • 有效注册：用户在2分钟内收到验证邮件，点击链接后可访问账户
  • 有效登录：用户输入正确凭据后，立即重定向至仪表盘
  • 密码重置请求：用户在2分钟内收到重置链接，链接1小时内有效

Error Scenarios

错误场景

  • Duplicate email: Show "An account with this email already exists" message
  • Weak password: Show specific requirements not met (e.g., "Password must include a number")
  • Failed login (1-2 attempts): Show "Invalid email or password" message
  • Failed login (3 attempts): Show "Account locked for 15 minutes due to too many failed attempts"
  • Expired reset link: Show "This reset link has expired. Please request a new one."
  • Unverified account login: Show "Please verify your email before logging in" with option to resend
  • 重复邮箱：显示“该邮箱已注册账户”信息
  • 弱密码：显示未满足的具体要求（如“密码必须包含数字”）
  • 登录失败（1-2次）：显示“邮箱或密码无效”信息
  • 登录失败（3次）：显示“因多次登录失败，账户已锁定15分钟”信息
  • 过期重置链接：显示“该重置链接已过期，请重新请求”信息
  • 未验证账户登录：显示“请先验证邮箱再登录”，并提供重新发送验证邮件的选项

Business Rules

业务规则

  • Email addresses must be unique across all accounts (case-insensitive: test@example.com = Test@Example.com)
  • Passwords must be at least 8 characters with 1 number and 1 special character (!@#$%^&*)
  • Passwords expire after 90 days and users must create a new one
  • New password cannot match previous 3 passwords
  • Verification emails expire after 24 hours
  • Users can't register with disposable email services (list maintained separately)
  • Account lockout after 3 failed attempts lasts exactly 15 minutes
  • Password reset links expire after 1 hour
  • Only one active reset link per account - requesting new one invalidates previous
  • 邮箱地址在所有账户中必须唯一（不区分大小写：test@example.com = Test@Example.com）
  • 密码长度至少8位，包含1个数字和1个特殊字符（!@#$%^&*）
  • 密码90天后过期，用户需创建新密码
  • 新密码不能与前3次使用的密码相同
  • 验证邮件24小时后过期
  • 用户无法使用临时邮箱服务注册（邮箱域名列表单独维护）
  • 3次登录失败后账户锁定时长恰好为15分钟
  • 密码重置链接1小时后过期
  • 每个账户仅允许存在一个有效的重置链接——新请求会使之前的链接失效

Dependencies

依赖关系

Required Features/Systems

所需功能/系统

  • Email delivery service: For verification and password reset emails. If service is down, registration/reset will fail gracefully with "Unable to send email, please try again later"
  • Session management: Required to maintain logged-in state
  • 邮件投递服务：用于发送验证邮件和密码重置邮件。若服务宕机，注册/重置操作会优雅失败，显示“无法发送邮件，请稍后重试”
  • 会话管理：用于维持登录状态

Affected Features

受影响的功能

  • User profile: Cannot be accessed without authentication
  • Dashboard: Requires active session
  • Settings: Changes require password re-confirmation
  • 用户资料：未认证无法访问
  • 仪表盘：需要有效会话
  • 设置：修改需重新确认密码

External Services

外部服务

  • Email service: SendGrid for transactional emails
  • Disposable email checker: API to validate email domains
  • 邮件服务：使用SendGrid发送事务性邮件
  • 临时邮箱检查器：用于验证邮箱域名的API

Common Issues & Edge Cases

常见问题与边缘情况

Multiple tabs/sessions: If user logs out in one tab, all other tabs should immediately reflect logged-out state. Currently handled via session token validation on each request.
Email service downtime: System will retry sending 3 times over 10 minutes. If all fail, user sees error message but account is created - they can request verification resend from login page.
Case sensitivity: Email addresses are stored lowercase and compared case-insensitively. "Test@Example.com" and "test@example.com" are treated as same user.
Timing attacks: Login error messages deliberately don't distinguish between "email not found" and "wrong password" to prevent account enumeration.
Clock skew: Reset links use server time, not user device time, to prevent timezone issues.
多标签页/会话：若用户在一个标签页登出，所有其他标签页应立即显示登出状态。当前通过每次请求验证会话令牌实现。
邮件服务宕机：系统会在10分钟内重试3次发送邮件。若全部失败，用户会看到错误信息，但账户已创建——可从登录页面重新请求验证邮件。
大小写敏感性：邮箱地址以小写存储，且比较时不区分大小写。“Test@Example.com”和“test@example.com”被视为同一用户。
时序攻击防护：登录错误信息故意不区分“邮箱不存在”和“密码错误”，以防止账户枚举。
时钟偏差：重置链接使用服务器时间而非用户设备时间，以避免时区问题。

Future Considerations

未来规划

  • Add two-factor authentication option
  • Support social login (Google, GitHub)
  • Add "Remember me" option for extended sessions

**Bad example:**

```markdown
  • 添加双因素认证选项
  • 支持社交登录（Google、GitHub）
  • 添加“记住我”选项以延长会话时长

**反面示例：**

```markdown

Authentication

认证

Uses JWT tokens with bcrypt hashing. The AuthController handles login() and register() methods. Password validation uses regex pattern /^(?=.[0-9])(?=.[!@#$%^&*])/.
Database schema includes users table with email, password_hash, and created_at columns.
*This is too technical - focuses on implementation rather than what/why/how from a user perspective.*
使用JWT令牌和bcrypt哈希。AuthController处理login()和register()方法。密码验证使用正则表达式/^(?=.[0-9])(?=.[!@#$%^&*])/。
数据库schema包含users表，字段有email、password_hash和created_at。
*该示例过于技术化——聚焦于实现而非用户视角的功能作用/原因/工作方式。*

Workflow: Documenting a New Feature

工作流：记录新功能

When a feature is complete:
  1. Identify the feature scope - What constitutes this "feature" from a user perspective?
  2. Create the doc file - Use a clear, descriptive name in 
    docs/
  3. Start with "What" - Describe what the feature does in simple terms
  4. Explain "Why" - What problem does it solve?
  5. Detail "How" - Walk through the behavior and logic
  6. Document expected behavior - Both success and error scenarios with specific examples
  7. List business rules - All validation and constraints that must be enforced
  8. Map dependencies - What this needs and what needs this
  9. Capture edge cases - Unusual scenarios and how they're handled
  10. Add to index - Add entry to 
    docs/README.md
    with summary and relationships
  11. Review for clarity - Would a non-developer understand this? Would an AI agent know what's expected?
功能完成后：
  1. 确定功能范围 - 从用户视角定义该“功能”包含哪些内容？
  2. 创建文档文件 - 在
    docs/
    文件夹中使用清晰的描述性名称
  3. 从“作用”开始 - 用简单语言描述功能的作用
  4. 解释“原因” - 解决了什么问题？
  5. 详细说明“工作原理” - 逐步描述行为和逻辑
  6. 记录预期行为 - 包含成功和错误场景的具体示例
  7. 列出业务规则 - 所有必须执行的验证和约束
  8. 梳理依赖关系 - 该功能依赖的内容以及依赖该功能的内容
  9. 记录边缘情况 - 异常场景及其处理方式
  10. 加入索引 - 在
    docs/README.md
    中添加条目，包含概述和关联关系
  11. 检查清晰度 - 非开发人员能理解吗？AI Agent能快速了解预期行为吗？

Workflow: Documenting an Existing Project

工作流：记录已有项目

When documenting a complete project without existing docs:
  1. Identify all features - Survey the project or use your knowledge of features
  2. Prioritize features - Start with core functionality, then supporting features
  3. Document each feature - Follow the template above
  4. Add to index - Add each feature to 
    docs/README.md
    after documenting it (see Feature Index section above for template)
  5. Link related features - Cross-reference where features interact in each doc
为无现有文档的完整项目编写文档时：
  1. 识别所有功能 - 调研项目或根据对功能的了解列出所有功能
  2. 优先级排序 - 从核心功能开始，再到辅助功能
  3. 记录每个功能 - 遵循上述模板
  4. 加入索引 - 每个功能文档完成后，添加至
    docs/README.md
    （参考上述功能索引部分的模板）
  5. 关联相关功能 - 在每个文档中交叉引用交互的功能

Tips for Quality Documentation

高质量文档技巧

Be Concrete

具体明确

  • ❌ "The system handles various error cases"
  • ✅ "If the email service is down, the system queues the message and retries every 5 minutes for up to 2 hours"
  • ❌ “系统处理各种错误情况”
  • ✅ “若邮件服务宕机，系统会将消息加入队列，每5分钟重试一次，最多重试2小时”

Use Scenarios

使用场景

  • ❌ "Supports bulk operations"
  • ✅ "Users can select multiple items and delete them all at once. If any item is locked or in use, the system shows which ones couldn't be deleted and why"
  • ❌ “支持批量操作”
  • ✅ “用户可选择多个项目并一次性删除。若任何项目被锁定或正在使用，系统会显示无法删除的项目及其原因”

Explain Decisions

解释决策

  • ❌ "Passwords must be 8+ characters"
  • ✅ "Passwords must be 8+ characters to balance security with usability - short enough to remember but long enough to resist common attacks"
  • ❌ “密码必须≥8位”
  • ✅ “密码必须≥8位，以平衡安全性与易用性——长度足够短以便记忆，同时足够长以抵御常见攻击”

Describe Edge Cases

描述边缘情况

  • ❌ "Handles payment processing"
  • ✅ "During payment processing, if the payment gateway times out, the system waits 30 seconds then checks the payment status directly. This prevents duplicate charges"
  • ❌ “处理支付流程”
  • ✅ “支付流程中，若支付网关超时，系统会等待30秒后直接检查支付状态。这可避免重复扣费”

Maintaining Documentation

文档维护

  • Update when behavior changes - Not when code changes, but when user-facing behavior or business logic changes
  • Keep it current - Remove or clearly mark deprecated features
  • Version significant changes - Note when major functionality was added or modified
  • Review periodically - Ensure docs still accurately reflect the product
  • 行为变更时更新 - 不是代码变更时更新，而是面向用户的行为或业务逻辑变更时更新
  • 保持时效性 - 删除或明确标记已弃用的功能
  • 版本化重大变更 - 记录主要功能的添加或修改时间
  • 定期审核 - 确保文档仍准确反映产品现状

Summary Checklist

总结检查清单

Before finalizing feature documentation:
最终确定功能文档前：

Core Content

核心内容

  • Explains what the feature does from a user perspective
  • Clarifies why this feature exists (problem/need)
  • Describes how it works without code references
  • Includes data flow overview
  • 从用户视角解释功能作用
  • 明确该功能存在的原因（问题/需求）
  • 不涉及代码地描述工作原理
  • 包含数据流概述

Expected Behavior (Critical for AI troubleshooting)

预期行为（AI故障排查关键）

  • Documents success scenarios with specific inputs and outputs
  • Documents error scenarios with expected error messages
  • Covers edge cases and unusual situations
  • Clarifies what should happen when dependencies fail
  • 记录包含具体输入和输出的成功场景
  • 记录包含预期错误信息的错误场景
  • 覆盖边缘情况和异常场景
  • 明确依赖项故障时的处理逻辑

Business Rules (Critical for AI troubleshooting)

业务规则（AI故障排查关键）

  • Lists all validation rules with specific examples
  • Documents constraints that must ALWAYS be enforced
  • Explains non-obvious logic that might seem like bugs
  • 列出所有带具体示例的验证规则
  • 记录必须始终执行的约束
  • 解释看似bug但实为有意设计的非直观逻辑

Integration & Dependencies

集成与依赖

  • Lists required features/systems with explanations
  • Lists features affected by this one
  • Documents external services and their purpose
  • Notes what happens when dependencies are unavailable
  • 列出所需功能/系统并解释原因
  • 列出受该功能影响的功能
  • 记录外部服务及其用途
  • 说明依赖项不可用时的处理逻辑

Common Issues

常见问题

  • Documents known edge cases
  • Explains gotchas or confusing behavior
  • Covers common failure modes
  • 记录已知边缘情况
  • 解释易混淆点
  • 覆盖常见失败模式

Quality

质量

  • Uses plain language a non-developer would understand
  • Provides concrete examples, not abstractions
  • Would help AI agent quickly understand expected behavior
  • File is saved in 
    docs/
    with a clear name
  • 使用非开发人员能理解的平实语言
  • 提供具体示例而非抽象描述
  • 能帮助AI Agent快速了解预期行为
  • 文件已保存至
    docs/
    文件夹，名称清晰