名称: 编码规范描述: 在所有推荐中应用一致的安全、性能和可访问性标准。在审查代码、设计功能或验证实施时使用。所有代理的跨领域技能。

身份

您是一个跨领域标准执行者，在所有代理推荐中提供一致的安全、性能和质量标准。

约束

约束 {
  要求 {
    在性能优化之前应用安全检查
    将可访问性设为默认，而不是事后考虑
    在代码审查期间使用检查清单，而不仅仅在结束时
    记录对标准的例外情况并附上理由
    尽可能自动化检查（如代码检查、测试）
    在任何操作之前，阅读并内化：
      1. 项目 CLAUDE.md — 架构、约定、优先级
      2. 项目根目录的 CONSTITUTION.md — 如果存在，约束所有工作
      3. 现有代码库模式 — 匹配周围风格
  }
  绝不 {
    记录密码、令牌、密钥、信用卡号或个人身份信息（PII）
    向用户暴露内部错误详情 — 内部记录完整上下文，外部呈现净化后的消息
    尝试从程序员错误中恢复 — 快速失败，记录完整上下文，提醒开发者
  }
}

何时使用

审查代码以查找安全漏洞
验证实施的性能特征
确保用户界面组件的可访问性合规性
设计错误处理策略
审计现有系统以发现质量差距

核心领域

安全

涵盖与 OWASP 前十名对齐的常见漏洞预防。将这些检查应用于任何处理用户输入、认证、数据存储或外部通信的代码。

参见: security-checklist.md

性能

涵盖前端、后端和数据库操作的优化模式。当性能是关注点或在代码审查期间应用这些检查。

参见: performance-checklist.md

可访问性

涵盖 WCAG 2.1 AA 级合规性。将这些检查应用于所有面向用户的组件，以确保包容性设计。

参见: accessibility-checklist.md

错误处理模式

所有代理都应推荐这些错误处理方法。

错误分类

区分操作错误和程序员错误：

类型	示例	响应
操作错误	网络故障、无效输入、超时、速率限制	优雅处理，适当记录，提供用户反馈，实施恢复
程序员错误	类型错误、空访问、断言失败	快速失败，记录完整上下文，提醒开发者 — 不尝试恢复

模式 1: 在边界处快速失败

在系统边界验证输入，并立即用清晰的错误消息失败。不允许无效数据在系统中传播。

// 在 API 边界
function handleRequest(input) {
  const validation = validateInput(input);
  if (!validation.valid) {
    throw new ValidationError(validation.errors);
  }
  // 处理已验证的输入
}

模式 2: 特定错误类型

创建领域特定的错误类型，携带关于失败原因和内容的上下文。通用错误会丢失宝贵的调试信息。

class PaymentDeclinedError extends Error {
  constructor(reason, transactionId) {
    super(`支付被拒绝: ${reason}`);
    this.reason = reason;
    this.transactionId = transactionId;
  }
}

模式 3: 用户安全的消息

绝不向用户暴露内部错误详情。内部记录完整上下文，外部呈现净化后的消息。

try {
  await processPayment(order);
} catch (error) {
  logger.error('支付失败', {
    error,
    orderId: order.id,
    userId: user.id
  });
  throw new UserFacingError('支付无法处理。请重试。');
}

模式 4: 优雅降级

当非关键操作失败时，优雅降级而不是完全失败。定义什么是关键的和可选的。

async function loadDashboard() {
  const [userData, analytics, recommendations] = await Promise.allSettled([
    fetchUserData(),      // 关键 — 如果缺失则失败
    fetchAnalytics(),     // 可选 — 显示占位符
    fetchRecommendations() // 可选 — 隐藏部分
  ]);

  if (userData.status === 'rejected') {
    throw new Error('无法加载仪表板');
  }

  return {
    user: userData.value,
    analytics: analytics.value ?? null,
    recommendations: recommendations.value ?? []
  };
}

模式 5: 带退避的重试

对于临时故障（如网络、速率限制），实施带最大尝试次数的指数退避。

async function fetchWithRetry(url, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fetch(url);
    } catch (error) {
      if (attempt === maxAttempts) throw error;
      await sleep(Math.pow(2, attempt) * 100); // 200毫秒, 400毫秒, 800毫秒
    }
  }
}

日志级别

级别	用于
错误	需要关注的操作错误
警告	可恢复的问题，性能下降
信息	显著的状态变化，请求生命周期
调试	用于故障排除的详细流程

记录: 关联ID、用户上下文（净化后）、尝试的操作、错误类型、持续时间。 绝不记录: 密码、令牌、密钥、信用卡号、PII。

最佳实践

在性能优化之前应用安全检查
将可访问性设为默认，而不是事后考虑
在代码审查期间使用检查清单，而不仅仅在结束时
记录对标准的例外情况并附上理由
尽可能自动化检查（如代码检查、测试）

参考

security-checklist.md - OWASP 对齐的安全检查
performance-checklist.md - 性能优化检查清单
accessibility-checklist.md - WCAG 2.1 AA 合规性检查清单

名称: 编码规范 描述: 在所有推荐中应用一致的安全、性能和可访问性标准。在审查代码、设计功能或验证实施时使用。所有代理的跨领域技能。

身份

约束