cclint (克劳德代码 Lint) Name

用于Claude Code项目的综合林入工具,用于验证代理定义,命令配置,设置文件和项目文档.

特征

• 代理/副代理Linting: 验证前题、工具配置和命名惯例
• 启动命令: 检查斜线命令定义和工具权限
• 设置验证: 验证 .claude/settings.json 钩形配置
• 文档 Linting:确保CLAUDE.md遵循最佳做法和模板结构
• 自定义外观支持: 与 Zod 一起扩展基准计划, 用于特定项目的验证
• 项目自动检测: 使用目录爬升自动查找工程根
• 多个输出格式: 控制台、 JSON和Markdown报告
• CI/CD 友好组织: 配置退出代码和静态模式

安装

# Install globally
npm install -g @carlrannaberg/cclint

# Install as dev dependency
npm install --save-dev @carlrannaberg/cclint

# Use without installing
npx @carlrannaberg/cclint

使用量

基本线性

# Lint current project (auto-detects root)
cclint

# Lint specific directory
cclint --root /path/to/project

# Quiet mode (minimal output)
cclint --quiet

# Verbose mode (show all files)
cclint --verbose

专业林廷

Lint 仅用于更快,有重点的验证的特定文件类型 :

# Lint only agent definition files
cclint agents

# Lint only command definition files  
cclint commands

# Lint only settings.json files
cclint settings

# Lint only CLAUDE.md context files
cclint context

# Use with options for specialized linting
cclint agents --verbose --follow-symlinks
cclint commands --root /path/to/project --quiet

报表生成

# Generate JSON report
cclint --format json --output lint-report.json

# Generate Markdown report
cclint --format markdown --output reports/lint-report.md

CI/CD 一体化

# Fail on errors only (default)
cclint --fail-on error

# Fail on warnings or errors
cclint --fail-on warning

# Fail on suggestions, warnings, or errors
cclint --fail-on suggestion

# Disable custom schema validation
cclint --no-custom-schemas

共线支持

# Follow symlinks when discovering files (secure by default)
cclint --follow-symlinks

# Symlinks are NOT followed by default for security
# When enabled, validates that symlink targets remain within project root
# Useful for projects with shared agent/command definitions

SDK/方案使用法

CCLint可以在您的节点.js应用程序中程序化地使用:

import CClint from '@carlrannaberg/cclint';

// Create linter instance
const linter = new CClint();

// Lint entire project
const summary = await linter.lintProject('./my-project', {
  quiet: true,
  followSymlinks: true  // Enable symlink support
});

// Lint specific file types
const agentResults = await linter.lintAgents('./my-project');
const commandResults = await linter.lintCommands('./my-project');

返回类型已解释

lintProject() 返回 a LintSummary数字 :

{
  totalFiles: 35,
  validFiles: 24,
  totalErrors: 11,
  totalWarnings: 2,
  totalSuggestions: 0,
  duration: 150,
  results: [...] // Array of all individual file results
}

lintAgents(), (中文(简体) ), lintCommands()等 (中文(简体) ). 返回时 LintResult[]数字 :

[
  {
    file: '/path/to/agent.md',
    valid: true,
    errors: [],
    warnings: [],
    suggestions: [],
    missingFields: []
  },
  // ... more individual file results
]

使用大小写

• lintProject(): 项目全面审定、CI/CD整合、综合报告
• lintAgents(): 仅验证代理人定义,对以代理人为重点的工具有用
• lintCommands(): 只验证命令定义, 对命令管理工具有用
• lintSettings(): 验证设置.json,用于配置工具

它检查什么

克洛德官方代码字段

cclint对照克洛德代码的官方规格进行验证. 任何额外的字段必须通过自定义的图案扩展来添加.

代理/代理前题字段

要求 :

• name - 代理标识符(小写,有连字符的字母数字)
• description - 关于何时援引的自然语言说明

可选 :

• tools 或者说 allowed-tools - 工具访问: "*" 面向所有人,或一系列工具名称
• model - 首选模式:相声、相声、相声、相声、相声、相声
• color - UI颜色(必须是:红色、蓝色、绿色、黄色、紫色、橙色、粉色、青色等颜色之一)

命令前题字段

所有字段都是可选的 :

• description - 命令描述( 默认从内容中第一个标题或行)
• allowed-tools - 命令可以使用的工具(字符串格式:“工具1,工具2”)
• argument-hint - UI 中显示的命令参数提示
• model - 使用模型(与剂值相同)

代理/代理文件 (*. md 有前题)

• 所需字段 : name, (中文(简体) ), description
• QQ 工具配置和语法
• • 颜色验证(8个有效的克洛德编码颜色:红色、蓝色、绿色、黄色、紫色、橙色、粉红色、青色)
• ✅ 命名公约和文件名匹配
• 未知工具和已贬值的字段
• 内容优化建议

命令文件 (*. md 有前题)

• QQ 前题方案验证
• 工具权限 : allowed-tools
• Bash 命令用途验证
• 文件参考模式
• 未知的工具和语法错误
• 缺少描述和参数提示

设置文件 (. claude/ settings.json)

• JSON 语法和计划验证
• 虎克配置结构
• 活动类型和匹配者
• 命令语法验证
• 未知的钩子事件和工具
• QQ 配置优化建议

文件(CLAUDE.md/AGENTS.md)

• · 所需各科的存在
• 文件结构验证
• QQ 模板遵守性检查
• 缺少的章节和内容
• 内容质量改进

项目结构检测

cclint 通过爬升目录自动检测您的工程根 :

• .git 目录
• package.json 文件
• .claude 目录

然后扫描常见位置的文件:

project-root/
├── .claude/
│   ├── settings.json     # Settings validation
│   ├── agents/           # Agent definitions
│   └── commands/         # Command definitions
├── src/
│   ├── agents/           # Alternative agent location
│   └── commands/         # Alternative command location
├── CLAUDE.md             # Documentation validation
└── AGENTS.md             # Alternative documentation

配置

cclint通过使用合理默认和自动检测来进行不配置的工作. 对于高级用途,可以:

1. 指定自定义路径 与 --root
2. 控制输出动词 与 --quiet编号 :--verbose
3. 选择输出格式 与 --format
4. 设定失败阈值 与 --fail-on
5. 创建自定义计划 带有配置文件

自定义外观配置

cclint支持用你自己的Zod schemas来扩展基础验证计划,以满足项目的特定要求.

配置文件

cclint 在以下文件中查找配置( 按优先级排序) :

• cclint.config.js - Java脚本配置
• cclint.config.mjs - ES模块配置
• cclint.config.ts - 类型脚本配置(需要汇编)
• .cclintrc.json - JSON配置
• .cclintrc.js - Java脚本配置
• .cclintrc.mjs - ES模块配置

JSON 配置示例

{
  "agentSchema": {
    "extend": {
      "priority": "number",
      "tags": "array",
      "experimental": "boolean"
    }
  },
  "commandSchema": {
    "extend": {
      "timeout": "number",
      "retryCount": "number"
    }
  },
  "rules": {
    "unknownFields": "warning",
    "strict": true,
    "excludePatterns": ["**/legacy/**"]
  }
}

JavaScript 配置示例

// cclint.config.js
import { z } from 'zod';

export default {
  agentSchema: {
    extend: {
      // Custom fields for agents
      priority: z.number().min(1).max(5).describe('Agent priority level'),
      tags: z.array(z.string()).optional().describe('Categorization tags'),
      experimental: z.boolean().optional().describe('Experimental feature flag'),
      owner: z.string().email().describe('Agent maintainer email')
    },
    customValidation: (data) => {
      const errors = [];
      
      // Custom validation logic
      if (data.experimental && !data.description?.includes('EXPERIMENTAL')) {
        errors.push('Experimental agents must include "EXPERIMENTAL" in description');
      }
      
      if (data.priority > 3 && !data.owner) {
        errors.push('High priority agents must have an owner assigned');
      }
      
      return errors;
    }
  },
  
  commandSchema: {
    extend: {
      timeout: z.number().positive().describe('Command timeout in milliseconds'),
      retryCount: z.number().min(0).max(3).default(0),
      async: z.boolean().optional().describe('Run command asynchronously')
    },
    customValidation: (data) => {
      const errors = [];
      
      if (data.async && !data.timeout) {
        errors.push('Async commands must specify a timeout');
      }
      
      return errors;
    }
  },
  
  settingsSchema: {
    extend: {
      // Custom settings fields
      customHooks: z.record(z.array(z.string())),
      teamSettings: z.object({
        lead: z.string(),
        members: z.array(z.string())
      }).optional()
    }
  },
  
  claudeMdRules: {
    requiredSections: [
      'project overview',
      'setup instructions', 
      'development workflow',
      'testing strategy'
    ],
    customValidation: (content, sections) => {
      const errors = [];
      
      if (!content.includes('## Security')) {
        errors.push('CLAUDE.md must include a Security section');
      }
      
      return errors;
    }
  },
  
  rules: {
    unknownFields: 'error',
    strict: true,
    includePatterns: ['custom-agents/**'],
    excludePatterns: ['**/legacy/**', '**/deprecated/**']
  }
};

类型脚本配置示例

// cclint.config.ts
import { z } from 'zod';
import type { CclintConfig } from 'cclint';

const AgentPriority = z.enum(['low', 'medium', 'high', 'critical']);

const config: CclintConfig = {
  agentSchema: {
    extend: {
      priority: AgentPriority,
      team: z.string().min(1),
      version: z.string().regex(/^\d+\.\d+\.\d+$/)
    }
  }
};

export default config;

Schema 覆盖示例

为了完全控制,您可以覆盖整个计划:

// cclint.config.js
import { z } from 'zod';

export default {
  agentSchema: {
    override: z.object({
      // Completely custom schema
      id: z.string().uuid(),
      name: z.string().min(1),
      version: z.string(),
      config: z.record(z.unknown())
    }).strict()
  }
};

配置选项

实例

GitHub 动作集成

name: Claude Code Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm install -g @carlrannaberg/cclint
      - run: cclint --fail-on warning

承诺前虎克

#!/bin/sh
# .git/hooks/pre-commit
cclint --quiet --fail-on error

报表生成脚本

#!/bin/bash
# scripts/lint-report.sh
mkdir -p reports
cclint --format markdown --output reports/claude-lint-$(date +%Y%m%d).md
echo "Lint report generated in reports/"

退出代码

• 0: 成功(无超过故障阈值的问题)
• 1: 故障(发现的问题高于故障阈值)

捐款

1. 叉子存储器
2. 创建特性分支
3. 做你的改变
4. 在适用的情况下添加测试
5. 提交拉动请求

许可证

麻省理工学院

相关项目

• 克劳德代码 - AI动力编码助理