name: notetaker-fundamentals description: 用于在代码中留下结构化笔记、评论和注解。涵盖AI笔记模式、TODO格式、上下文保存以及为未来AI助手和人类开发者准备的开发面包屑。 allowed-tools:

Read
Write
Edit
Bash
Grep
Glob

AI辅助开发的笔记记录基础

为AI助手在代码库中留下有意义的上下文的有效笔记模式。

哲学

当AI助手修改代码时，它们应该为未来的AI助手和人类开发者留下面包屑。笔记应该：

保存上下文关于为什么做出决策
标记不确定性存在替代方法的地方
标记未完成的工作需要跟进
链接到相关上下文（问题、PR、文档）
解释不明显的模式可能让读者困惑

笔记格式

AI开发笔记

AI到AI通信的特殊注释格式：

// AI-DEV-NOTE: 此函数使用缓存优先策略，因为数据很少变化，且网络调用导致性能问题。参见PR #123中的性能分析。

# AI-DEV-NOTE: 验证顺序在这里很重要 - 必须先检查身份验证，再检查授权，以避免泄露用户存在信息。
# 考虑了使用中间件的替代方法，但由于复杂性增加而被拒绝。

何时使用：

解释不明显的实现决策
记录考虑过的替代方法
链接到相关上下文（PR、问题、讨论）
警告关于微妙的bug或边缘情况
保存未来重构决策的理由

结构化TODO注释

带有上下文的增强TODO格式：

// TODO(ai/context): 将此验证逻辑提取到单独的验证器类。目前在3个地方重复：
// - src/api/users.ts:45
// - src/api/auth.ts:78
// - src/validators/user.ts:12
// 被阻塞于：等待PR #456合并验证器基类

// TODO(ai/performance): 应优化此O(n²)循环。分析显示当n > 100时，请求时间的45%花费在此处。
// 考虑：哈希映射查找或排序后二分搜索。
// 影响：高 - 影响主要用户流程
// 工作量：中等 - 预计2-3小时

TODO格式结构：

// TODO(ai/<category>): <简要描述>
// <额外上下文>
// <替代方法>
// <阻塞项/依赖项>
// <影响/优先级>

常见类别：

ai/refactor - 代码结构改进
ai/performance - 优化机会
ai/security - 安全考虑
ai/accessibility - A11y改进
ai/testing - 测试覆盖缺口
ai/docs - 文档需求
ai/context - 上下文保存
ai/edge-case - 未处理的边缘情况

决策记录

重要选择的嵌入式决策记录：

// DECISION: 使用Arc<RwLock<T>>而非Mutex<T>
// RATIONALE: 读取密集型工作负载（95%读取，5%写入）受益于RwLock的并发读取访问。基准测试显示在典型负载模式下RwLock的吞吐量提高了3倍。
// ALTERNATIVES_CONSIDERED:
//   - Mutex<T>: 更简单，但对于读取密集型工作负载较慢
//   - atomic类型: 不适合复杂状态
// DATE: 2025-12-04
// AUTHOR: Claude (AI助手)

何时使用决策记录：

在竞争模式/库之间选择
性能权衡（内存vs速度等）
影响多个文件的架构决策
安全敏感选择
未来可能被质疑的决策

上下文保存

为未来理解留下面包屑：

// CONTEXT: 这个看起来奇怪的变通方案是必要的，因为Safari不支持标准API（截至v17.2）。已提交webkit bug：
// https://bugs.webkit.org/show_bug.cgi?id=123456
// 当Safari支持时删除此部分（检查caniuse.com）
if (isSafari) {
  // 回退实现
}

# CONTEXT: 数据库迁移添加了'deleted_at'列（migration_003），但在过渡期间仍使用'is_deleted'以保持向后兼容性。
# 当所有旧记录迁移后（2025-12-31之后）可以删除'is_deleted'。

不确定性标记

标记AI不确定的区域：

// AI-UNCERTAIN: 这可能无法正确处理DST转换期间的时区边缘情况。建议由熟悉时区处理的开发人员进行手动审查。

// AI-UNCERTAIN: 不确定这在所有场景下是否线程安全。考虑添加同步或由并发专家审查。

笔记放置指南

放置笔记的位置

良好放置：

// AI-DEV-NOTE: 复杂业务逻辑如下 - 实现了docs/workflows.md中描述的三级审批工作流
function processApproval(request: ApprovalRequest) {
  // 实现...
}

不良放置：

function processApproval(request: ApprovalRequest) {
  const step1 = validate(request);
  // AI-DEV-NOTE: 整个函数复杂
  const step2 = process(step1);
  // 不良 - 笔记被埋在实现细节中
}

邻近规则

将笔记直接放置在描述代码之前
对于文件级笔记，放置在导入之后顶部
对于函数级笔记，直接放置在函数之前
对于内联笔记，放置在相关代码的上一行

笔记密度

避免过度注释：

// ❌ 笔记过多
// AI-DEV-NOTE: 解析用户输入
const input = parseInput(raw);
// AI-DEV-NOTE: 验证输入
const valid = validate(input);
// AI-DEV-NOTE: 处理结果
const result = process(valid);

// ✅ 适当密度
// AI-DEV-NOTE: 标准验证流程 - 解析、验证、处理
// 每个步骤可能抛出ValidationError，由中间件处理
const input = parseInput(raw);
const valid = validate(input);
const result = process(valid);

交叉引用

链接到问题/PR

// AI-DEV-NOTE: 实现来自问题 #1234的用户故事
// 参见PR #1245对替代方法的讨论

链接到文档

# AI-DEV-NOTE: 算法在docs/algorithms/rate-limiting.md中解释
# 基于令牌桶算法：https://en.wikipedia.org/wiki/Token_bucket

链接到其他代码

// AI-DEV-NOTE: api/v2/handlers.go:123中验证逻辑的镜像
// 保持这些同步或提取到共享验证器

笔记维护

过期日期

对于临时笔记或变通方案：

// AI-DEV-NOTE: API v1兼容性的临时变通方案
// REMOVE_AFTER: 2025-12-31（当v1 API完全弃用时）

# TODO(ai/temporary): 使用占位实现
# REPLACE_WHEN: 真实身份验证服务部署时

笔记更新

当修改带有现有笔记的代码时：

// AI-DEV-NOTE: [更新于 2025-12-04] 最初使用同步处理，但切换到异步以防止UI阻塞。
// 为上下文保留先前笔记。
// [原始 2025-11-15] 此处理项目同步...

反模式

避免

❌ 留下模糊的笔记

// AI-DEV-NOTE: 这很重要
// 不良 - 没有关于为什么重要的上下文

❌ 过度解释明显的代码

# AI-DEV-NOTE: 这将计数器增加1
count += 1  # 从代码中显而易见

❌ 留下没有可操作信息的笔记

// TODO: 修复此问题
// 不良 - 没有关于需要修复什么或如何修复的上下文

❌ 重复提交消息中已有的信息

// AI-DEV-NOTE: 添加了错误处理
// 不良 - 提交消息已经说了这个

应该

✅ 提供具体、可操作的上下文

// AI-DEV-NOTE: 订单验证必须在库存检查之前发生，以防止物品被预留但无效的竞争条件

✅ 解释“为什么”而不是“什么”

# AI-DEV-NOTE: 使用二分搜索而非线性搜索，因为数据集可能超过10k项（分析显示平均延迟为300ms）

✅ 包括具体后续步骤

// TODO(ai/refactor): 将重复验证提取到共享验证器
// 要更新的文件：api/users.ts, api/teams.ts, api/projects.ts
// 预计工作量：1-2小时

✅ 链接到外部上下文

// AI-DEV-NOTE: 实现RFC 6749 OAuth 2.0授权框架
// https://tools.ietf.org/html/rfc6749#section-4.1

按语言示例

TypeScript/JavaScript

/**
 * AI-DEV-NOTE: 此函数使用防抖方法以避免快速用户输入期间的过多API调用。300ms延迟通过用户测试确定，以平衡响应性和服务器负载。参见分析仪表板指标。
 *
 * TODO(ai/performance): 考虑为正在进行的请求实现取消机制，当用户继续输入时。目前依赖服务器端去重，这不理想。
 */
export function searchUsers(query: string): Promise<User[]> {
  // 实现...
}

Python

# AI-DEV-NOTE: 此类实现Repository模式以抽象数据库访问。所有数据库操作应通过仓库方法进行，以保持一致性和启用更轻松的模拟仓库测试。
#
# DECISION: 全程使用async/await因为：
# 1. 数据库I/O本质上是异步的
# 2. 允许批量更新的并发操作
# 3. 防止在FastAPI中阻塞事件循环
#
# 替代（同步SQLAlchemy）被拒绝，因为它需要在线程池中运行，增加了复杂性。

class UserRepository:
    def __init__(self, db: AsyncSession):
        self.db = db

    # TODO(ai/caching): 为频繁访问的用户（从日志识别：用户个人资料视图占DB查询的40%）添加Redis缓存层。预计影响：减少60%数据库负载。被阻塞于：Redis基础设施设置
    async def get_by_id(self, user_id: int) -> Optional[User]:
        # 实现...
        pass

Go

// AI-DEV-NOTE: 此中间件使用OpenTelemetry实现请求追踪。每个请求获得唯一的追踪ID，贯穿整个请求生命周期，使调试分布式系统更容易。
//
// CONTEXT: 选择OpenTelemetry而非自定义追踪因为：
// - 行业标准，支持广泛工具
// - 兼容Jaeger、Zipkin和云提供商
// - 维护负担低于自定义解决方案
//
// 配置在config/telemetry.yaml中
func TracingMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // AI-UNCERTAIN: 采样率（10%）可能对于调试罕见问题太低。考虑基于错误率或请求模式的动态采样。需要监控数据以做出明智决策。

        // 实现...
    }
}

Rust

// AI-DEV-NOTE: 此实现使用不安全代码以实现零拷贝解析。安全不变量是：
// 1. 输入缓冲区必须比所有返回的引用更长寿
// 2. 解析期间不能存在可变别名
// 3. UTF-8有效性在转换前检查
//
// SAFETY: 这些不变量被维护因为：
// - 缓冲区为'a生命周期借用（类型系统强制执行）
// - 解析器在解析期间被消耗（不可能有可变别名）
// - from_utf8_unchecked仅在验证后调用
//
// TODO(ai/safety): 考虑添加模糊测试以验证在畸形输入下的安全假设。当前测试覆盖对于有效输入良好，但边缘情况可能破坏不变量。
unsafe fn parse_str<'a>(buf: &'a [u8]) -> Result<&'a str, ParseError> {
    // 实现...
}

与开发工作流集成

提交前审查

提交前，AI应审查笔记：

确保所有AI-UNCERTAIN笔记有相应的测试覆盖
检查TODO(ai/*)笔记有足够的上下文供后续跟进
验证链接到问题/PR有效
删除或更新过时笔记

笔记提取

团队可以提取AI笔记进行审查：

# 查找所有AI开发笔记
grep -r "AI-DEV-NOTE" src/

# 查找所有AI TODOs
grep -r "TODO(ai/" src/

# 查找需要审查的不确定区域
grep -r "AI-UNCERTAIN" src/

笔记分析

追踪笔记模式以改进AI辅助：

AI-UNCERTAIN笔记密度（指示置信度）
TODO(ai/*)笔记类别（指示常见问题）
笔记年龄（指示维护负担）

AI开发笔记基础Skill notetaker-fundamentals