mcpField
A
agentic-docs

agentic-docs

github.com/petekp开发1051 次安装21 周前更新
代码仓库

关于 agentic-docs

帮助开发者在代码旁撰写简明文档的技能，强调说明原因、接口约定、边界情况和架构选择，面向团队成员与 AI 助手。

主要功能

  1. 01文件与模块用途说明
  2. 02函数约定与边界情况
  3. 03聚焦原因的注释
  4. 04架构权衡说明
  5. 05特定语言的文档写法

适用场景

  1. 01为团队成员说明陌生代码
  2. 02解释不直观的实现决策
  3. 03为 AI 助手编写代码文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/petekp/agent-skills --skill agentic-docs

安装后在 Claude Code 中输入/agentic-docs确认已加载。

附带文件references/language-examples.md

详细介绍

Agentic Docs

编写与所描述代码同处一处的文档。使用浅显的语言，不用术语。解释为什么，而不是是什么。

核心理念

就近编写效果最好。 分开存放的文档会逐渐与代码脱节。代码旁的注释能保持准确，因为它们会随代码一起更新。

面向三类读者：

  1. 六个月后的自己
  2. 阅读陌生代码的队友
  3. 一次只能看到一个文件的 AI 助手（Claude、Copilot）

“为什么”测试： 编写注释前，先问自己：“这是否解释了这段代码为什么存在，或为什么要这样工作？” 如果只是重述代码做了什么，就不要写。

文档层级

文件头注释

每个文件开头都应简要说明其用途，以及它在整个系统中的作用。

// UserAuthContext.tsx
//
// Manages authentication state across the app. Wraps the root component
// to provide login status, user info, and auth methods to any child.
//
// Why a context instead of Redux: Auth state is read-heavy and rarely
// changes mid-session. Context avoids the ceremony of actions/reducers
// for something this simple.

// NetworkRetryPolicy.swift
//
// Handles automatic retry logic for failed network requests.
// Uses exponential backoff with jitter to avoid thundering herd
// when the server comes back online after an outage.
//
// Used by: APIClient, BackgroundSyncManager
// See also: NetworkError.swift for error classification

包括：

  • 此文件／模块负责什么
  • 它存在的原因（如果从名称中看不出来）
  • 与代码库其他部分的关系
  • 不明显的设计决策
函数和方法文档

记录契约，而非实现。

/**
 * Calculates shipping cost based on weight and destination.
 *
 * Uses tiered pricing: under 1lb ships flat rate, 1-5lb uses
 * regional rates, over 5lb triggers freight calculation.
 *
 * Returns $0 for destinations we don't ship to rather than
 * throwing. Caller should check `canShipTo()` first if they
 * need to distinguish "free shipping" from "can't ship."
 */
function calculateShipping(weightLbs: number, zipCode: string): number

def sync_user_preferences(user_id: str, prefs: dict) -> SyncResult:
    """
    Pushes local preference changes to the server and pulls remote changes.

    Conflict resolution: server wins for security settings, local wins
    for UI preferences. See PREFERENCES.md for the full conflict matrix.

    Called automatically on app foreground. Can also be triggered manually
    from Settings > Sync Now.
    """

包括：

  • 函数实现的目标（而非实现方式）
  • 不明显的参数限制或边缘情况
  • 返回值的含义，尤其是含义模糊的情况
  • 副作用（网络调用、文件写入、状态修改）

无需记录： 简单的 getter、显而易见的单行代码、名称描述清楚的私有辅助函数。

行内注释

谨慎使用。确有必要时，解释原因。

// Debounce search by 300ms to avoid hammering the API on every keystroke.
// 300ms feels responsive while cutting API calls by ~80% in user testing.
const debouncedSearch = useMemo(
  () => debounce(executeSearch, 300),
  [executeSearch]
);

// Force unwrap is safe here: viewDidLoad guarantees the storyboard
// connected this outlet. If it's nil, we want to crash immediately
// rather than fail silently later.
let tableView = tableView!

# Process oldest items first. Newer items are more likely to be
# modified again, so processing them last reduces wasted work.
queue.sort(key=lambda x: x.created_at)
架构注释

对于体现重要设计决策的代码，说明其中的权衡。

// ARCHITECTURE NOTE: Event Sourcing for Cart
//
// Cart state is rebuilt from events (add, remove, update quantity)
// rather than stored directly. This lets us:
// - Show complete cart history to users
// - Replay events for debugging
// - Retroactively apply promotions to past actions
//
// Tradeoff: Reading current cart state requires replaying all events.
// We cache the computed state in Redis with 5min TTL to keep reads fast.
// Cache invalidation happens in CartEventHandler.

// WHY COORDINATOR PATTERN
//
// Navigation logic lives here instead of in view controllers because:
// 1. VCs don't need to know about each other (loose coupling)
// 2. Deep linking becomes straightforward; just call coordinator methods
// 3. Navigation is testable without instantiating UI
//
// The tradeoff is more files and indirection. Worth it for apps with
// 10+ screens; overkill for simple apps.
TODO 注释

确保其可执行、可追踪。

// TODO(pete): Extract to shared util once mobile team needs this too.
// Blocked on: Mobile API parity (see MOBILE-123)

// HACK: Workaround for Safari flexbox bug. Remove after dropping Safari 14.
// Bug report: https://bugs.webkit.org/show_bug.cgi?id=XXXXX

// FIXME: Race condition when user rapidly toggles. Need to cancel
// in-flight requests. Reproduced in issue #892.

特定语言的写法

详细示例见 references/language-examples.md：

  • TypeScript/JavaScript（JSDoc、TSDoc 写法）
  • Swift（文档注释、MARK pragma）
  • Python（文档字符串、类型提示文档）
  • React/Next.js（组件文档写法）

写作风格

使用浅显的语言。 像是在向一位聪明但不了解背景的同事解释。

使用主动语态。 写“此函数会验证……”，而不是“执行了验证……”。

具体明确。 写“以 1 秒间隔重试 3 次”，而不是“处理重试”。

省略显而易见的内容。 如果代码写着 user.isAdmin，就不要注释“检查用户是否为管理员”。

为有时效性的内容注明日期。 对于变通方案、特定版本代码和临时解决方案，应注明何时可以移除。

引用常量，不重复数值。 如果某种行为由常量控制，就用名称引用它，不要在注释中重复它的值。

// Bad: duplicates the value, will drift when constant changes
/// Returns true if stale (not updated in last 5 minutes)
pub fn is_stale(&self) -> bool { ... }

// Good: references the constant
/// Returns true if stale (not updated within [`STALE_THRESHOLD_SECS`])
pub fn is_stale(&self) -> bool { ... }

将单位换算写在注释中是可以的（1048576 // 1MB），因为这样能增加清晰度，而不是重复信息。

评论

支持 Markdown