规则、钩子与安全

Codex 规则系统

规则系统是 Codex 中用于定义和强制执行代码质量、安全性和风格标准的框架。

规则定义

规则在 .claude/rules/ 目录下定义，每个规则文件使用 Markdown 格式：

# .claude/rules/code-style.md

## 代码风格规则

### 命名规范
- 组件使用 PascalCase：`UserProfile.tsx`
- 函数使用 camelCase：`getUserData()`
- 常量使用 UPPER_SNAKE_CASE：`MAX_RETRY_COUNT`
- 文件命名与默认导出一致

### 导入顺序
1. 外部依赖（react, next 等）
2. 内部模块（@/components, @/lib 等）
3. 类型定义
4. 样式文件

### 组件规范
- 每个组件文件只导出一个主要组件
- 使用命名导出导出子组件和类型
- 组件必须定义 PropTypes 或 TypeScript 接口

规则优先级

# .claude/rules/security.md
# rule: severity=critical
# applies-to: src/app/api/**, src/lib/auth/**

## 安全规则

- 所有 API 路由必须进行身份验证
- 用户输入必须经过验证和清理
- 敏感数据必须加密存储
- 错误信息不能泄露内部实现细节

规则应用

规则可以按目录、文件类型或模式匹配应用：

{
  "rules": {
    "code-style": {
      "applyTo": ["src/**/*.ts", "src/**/*.tsx"],
      "severity": "warning",
      "autoFix": true
    },
    "security": {
      "applyTo": ["src/app/api/**", "src/lib/auth/**"],
      "severity": "error",
      "autoFix": false
    },
    "testing": {
      "applyTo": ["src/**/*.test.ts"],
      "severity": "info",
      "autoFix": false
    }
  }
}

规则类型

钩子机制（Hooks）

钩子允许您在特定事件发生时执行自定义逻辑，实现工作流的自动化和定制。

钩子类型

配置钩子

在 settings.json 中配置钩子：

{
  "hooks": {
    "preCommand": {
      "script": "./hooks/check-command.sh",
      "timeout": 5000,
      "onFailure": "block"
    },
    "postEdit": {
      "script": "./hooks/lint-check.sh",
      "timeout": 10000,
      "onFailure": "warn"
    },
    "preCommit": {
      "script": "./hooks/review-changes.sh",
      "timeout": 30000,
      "onFailure": "block"
    }
  }
}

自定义钩子脚本

#!/bin/bash
# hooks/check-command.sh
# 在命令执行前检查是否在白名单中

COMMAND="$1"
ALLOWED_COMMANDS=("npm" "npx" "git" "node" "yarn" "pnpm")

for allowed in "${ALLOWED_COMMANDS[@]}"; do
  if [[ "$COMMAND" == "$allowed"* ]]; then
    exit 0
  fi
done

echo "命令不在白名单中: $COMMAND"
exit 1

#!/bin/bash
# hooks/lint-check.sh
# 在文件编辑后运行 lint

FILE_PATH="$1"
npx eslint --fix "$FILE_PATH"
exit $?

企业安全管理

安全策略配置

针对企业环境的安全策略配置：

{
  "security": {
    "policy": {
      "version": "1.0",
      "enforced": true
    },
    "authentication": {
      "required": true,
      "method": "sso",
      "provider": "okta"
    },
    "audit": {
      "enabled": true,
      "logAllOperations": true,
      "retentionDays": 90,
      "storage": "s3://audit-logs/"
    },
    "network": {
      "allowedDomains": ["api.github.com", "registry.npmjs.org"],
      "blockedDomains": ["*.malicious.com"],
      "requireTLS": true
    }
  }
}

数据保护

{
  "security": {
    "dataProtection": {
      "maskSecrets": true,
      "secretPatterns": [
        "api[_-]key",
        "secret",
        "token",
        "password",
        "credential"
      ],
      "preventExposure": true,
      "autoRedact": true
    }
  }
}

访问控制

{
  "security": {
    "accessControl": {
      "modelAccess": {
        "allowedModels": ["claude-3-opus", "claude-3-sonnet"],
        "blockedModels": []
      },
      "featureAccess": {
        "webSearch": false,
        "fileUpload": true,
        "codeExecution": true
      },
      "timeRestrictions": {
        "enabled": false,
        "allowedHours": "09:00-18:00"
      }
    }
  }
}

审计日志

日志配置

{
  "audit": {
    "enabled": true,
    "format": "json",
    "logFile": "/var/log/claude-code/audit.log",
    "rotate": {
      "maxSize": "100MB",
      "maxFiles": 10
    },
    "capture": {
      "commands": true,
      "fileChanges": true,
      "modelResponses": false,
      "userInput": false
    }
  }
}

日志格式

{
  "timestamp": "2026-06-03T10:30:00Z",
  "sessionId": "sess_abc123",
  "userId": "user_xyz",
  "project": "my-app",
  "action": "edit_file",
  "target": "src/app/page.tsx",
  "status": "success",
  "duration": 1234,
  "tokensUsed": 567
}

审计报告生成

#!/bin/bash
# generate-audit-report.sh

claude -p "
分析 /var/log/claude-code/audit.log 的审计日志：
1. 统计过去一周的操作次数和类型
2. 识别异常操作模式
3. 列出所有被拒绝的操作请求
4. 生成安全建议报告
" --format json > security-report.json

安全最佳实践

1. 最小权限原则：只授予必要的文件和命令权限
2. 配置审计：定期审查权限配置和操作日志
3. 敏感信息保护：使用环境变量管理密钥，避免在代码中硬编码
4. 钩子验证：在关键操作前使用钩子进行验证
5. 定期更新：保持 Codex 及其扩展的最新版本
6. 团队策略：在企业环境中统一配置安全策略
7. 培训意识：确保团队成员了解 Codex 的安全特性