@akson/cortex-doc-标准

Cortex寄存器的文件标准和工具。 为克洛德AI工作流程提供CLAUDE.md生成,文档规则,MCP服务器集成,LLM优化等功能.

特征

• 📝 CLAUDE.MD 一代人组织 - 从规则生成优化的 CLAUDE.md 文件
• 🔧 规则管理 - 制定和管理文件规则
• 🔌 MCP 服务器 - Claude AI集成的模型上下文协议服务器
• 🎯 标准执行 - 文件质量和命名公约
• 🚀 CLI 工具 - 用于共同任务的简单命令行接口

安装

npm install @akson/cortex-doc-standards

快速启动

# Initialize rules in your project
npx cortex-doc-standards rules init

# Generate CLAUDE.md from rules
npx cortex-doc-standards generate

# Start MCP server for Claude AI
npx cortex-doc-standards-mcp

配置示例

不同项目类型的准备使用配置示例:

# Copy a project-specific example
cp node_modules/@akson/cortex-doc-standards/examples/nextjs-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/monorepo-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/flutter-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/backend-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/makerkit-monorepo-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/makerkit-flutter-config.json ./doc-standards.config.json

# Or start with the comprehensive base example
cp node_modules/@akson/cortex-doc-standards/examples/base-config.json ./doc-standards.config.json

可用实例 :

• 基础配置.json - 有所有规则的全面配置
• 下一个js- config.json - 下一个带有 TypeScript & Prisma 的应用程序
• (原始内容存档于2018-02-05). monorepo-config.json - 有共享软件包的涡轮单簧管
• flutter-config.json (英语) - 跨平台 Flutter 移动应用程序
• 后端配置.json - 有数据库的节点.js API服务器
• 马克特-莫诺雷波-config.json - Turborepo公司的MakerKit SaaS框架
• (原始内容存档于2018-09-21). makerkit-flutter-config.json - MakerKit网络+Flutter移动跨平台

见 实例/README.md 用于详细的配置指南.

CLI 命令

CLAUDE.md 世代(建议的工作流程)

# 1. Initialize rules configuration (auto-detects project type)
npx cortex-doc-standards rules init

# 2. Edit .cortex-doc-standards/rules.json to customize your rules

# 3. Generate CLAUDE.md from your rules
npx cortex-doc-standards generate

现行规则

该套件包括6个最优化的内置规则,涵盖了AI辅助开发的所有方面:

规则配置变量

每个规则都通过变量支持定制. 以下是每项规则的关键变量:

claude-essentials

{
  "package.file": "package.json",           // Package config file
  "translation.function": "t",              // i18n function name
  "lint.command": "pnpm lint",             // Linting command
  "typecheck.command": "pnpm typecheck",   // Type checking command
  "test.command": "pnpm test"              // Test command
}

security-standards

{
  "secrets.manager": "1Password",          // Secrets management system
  "auth.method": "Supabase Auth",          // Authentication method
  "security.scanCommand": "pnpm audit"    // Security scan command
}

testing-standards

{
  "coverage.unit": "80",                   // Minimum unit test coverage
  "test.unit": "pnpm test",               // Unit test command
  "test.integration": "pnpm run test:integration",
  "test.e2e": "pnpm run test:e2e",
  "test.watch": "pnpm run test:watch",
  "test.coverage": "pnpm run test:coverage",
  "test.directory": "__tests__",          // Test directory
  "test.extension": "ts"                  // Test file extension
}

project-workflow

{
  "packages.namespace": "@akson",         // Package namespace
  "package.manager": "pnpm"              // Package manager
}

makerkit-complete (MakerKit项目)

{
  "dev.command": "pnpm dev",              // Development start command
  "dev.filter": "pnpm --filter web dev", // Filtered dev command
  "build.command": "pnpm build",         // Build command
  "db.start": "pnpm supabase:web:start", // Database start
  "db.reset": "pnpm supabase:web:reset", // Database reset
  "db.typegen": "pnpm supabase:web:typegen", // Type generation
  "package.build": "pnpm --filter @kit/ui build",
  "package.add": "pnpm --filter web add lodash",
  "package.manager": "pnpm",
  "package.filter": "pnpm --filter"
}

配置最佳做法

项目类型检测

CLI 根据 :

• 下一个.js时间: next 依赖性
• 单曲数字 : turbo 扶养或 workspaces 装入包裹
• 小蝶头数字 : pubspec.yaml 文件
• 后端数字 : express, (中文(简体) ), fastify,或 koa 依赖关系

自定义您的工程规则

基本规则( 永远包括)

{
  "rules": [
    { "id": "claude-essentials", "enabled": true },
    { "id": "code-standards", "enabled": true },
    { "id": "security-standards", "enabled": true }
  ]
}

为 MakerKit 项目

{
  "rules": [
    // ... essential rules
    { "id": "makerkit-complete", "enabled": true }
  ]
}

共享软件包的项目

{
  "rules": [
    // ... essential rules
    {
      "id": "project-workflow",
      "enabled": true,
      "variables": {
        "packages.namespace": "@your-org",
        "package.manager": "pnpm"
      }
    }
  ]
}

从旧版本迁移

若您有旧规则生成的 CLAUDE.md:

1. 备份您的当前 CLAUDE.md数字 : cp CLAUDE.md CLAUDE.md.backup
2. 初始化新规则数字 : npx cortex-doc-standards rules init
3. 自定义配置编辑 .cortex-doc-standards/rules.json
4. 重新生成数字 : npx cortex-doc-standards generate
5. 比较和合并: 审查备份中自定义的内容

解决问题

共同问题

"没有找到规则配置"

# Solution: Initialize rules first
npx cortex-doc-standards rules init

“无效配置”出错

• 请检查JSON 语法:确保 JSON 有效 .cortex-doc-standards/rules.json
• 验证规则标识: 只使用上列规则 ID
• 检查可变格式:确保所有变量都是字符串

未知规则 ID 警告

• 更新软件包数字 : npm install @akson/cortex-doc-standards@latest
• 检查拼写: 准确验证规则 ID 匹配( 区分大小写)

未替换变量

• 检查牙套: 变量必须使用 {variable.name} 格式
• 校验位置: 变量仅在规则模板内工作
• 检查范围: 确保为特定规则定义变量

设置配置( P)

cortex-doc-standards init --type <nextjs|flutter|backend|shopify|monorepo>
cortex-doc-standards config                    # Show current config
cortex-doc-standards health --verbose          # System health check

验证和质量

cortex-doc-standards validate                  # Validate all docs
cortex-doc-standards validate --file README.md # Single file
cortex-doc-standards validate --fix            # Auto-fix issues
cortex-doc-standards claude-check              # Claude AI standards check
cortex-doc-standards github-check              # GitHub Projects integration check

模板生成( G)

cortex-doc-standards templates                 # List available templates
cortex-doc-standards generate claude --project-name MyProject --output CLAUDE.md
cortex-doc-standards generate <template> --project-type nextjs

报告和分析

cortex-doc-standards report --format table     # Human-readable report
cortex-doc-standards report --format json      # Machine-readable JSON
cortex-doc-standards naming --dry-run          # Preview naming fixes
cortex-doc-standards naming --fix              # Apply naming conventions

项目整合

1. 初始化文件标准

cd your-project/
cortex-doc-standards init --type nextjs
# Creates cortex-docs.config.json with project-specific rules

2. 配置规则(cortex-docs.config.json)

{
  "name": "my-project",
  "type": "nextjs",
  "docsPath": "docs/",
  "claudePath": "CLAUDE.md",
  "rules": {
    "maxLines": 100,
    "minCodeBlockPercentage": 30,
    "requiredSections": ["Usage"],
    "blockedPatterns": [
      "This document provides",
      "Historical context",
      "Phase 1, Phase 2"
    ],
    "claudeEmojis": {
      "required": true,
      "validEmojis": ["🟣", "🟠"]
    },
    "enforcementLevel": "error"
  }
}

3. 加入CI/CD管道

# .github/workflows/docs-quality.yml
name: Documentation Quality
on: [push, pull_request]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npx @akson/cortex-doc-standards validate
      - run: npx @akson/cortex-doc-standards naming --dry-run

4. 承诺前虎克

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "cortex-doc-standards validate --fix"
    }
  }
}

程序用途

import { ConsolidatedCLI } from "@akson/cortex-doc-standards/cli";

// Use CLI programmatically
const cli = new ConsolidatedCLI();
await cli.run();

可用出口

// Main package
import { ConsolidatedCLI } from "@akson/cortex-doc-standards";

// CLI module
import { ConsolidatedCLI } from "@akson/cortex-doc-standards/cli";

// MCP server
import { DocStandardsMCPServer } from "@akson/cortex-doc-standards/mcp";

// Core validator
import { DocumentationValidator } from "@akson/cortex-doc-standards/core";

// Standards
import { GITHUB_PROJECTS_STANDARDS } from "@akson/cortex-doc-standards/standards";

统一规则迁移

统一的规则系统消除了零散的规则定义,为所有文件标准提供了单一的真理来源.

密钥更改

• 一个规则类型 - 导入 UnifiedRule 而不是遗留的变体.
• 一个验证符 - 使用 UnifiedDocumentationValidator 或 createValidator() 工厂.
• 共享默认 - 消费 DEFAULT_UNIFIED_RULES 用于基线配置.
• 中央封锁模式 - 延长 BASE_BLOCKED_PATTERNS 而不是保持相控阵列.

import {
  UnifiedDocumentationValidator,
  UnifiedRule,
  createValidator,
  DEFAULT_UNIFIED_RULES,
  BASE_BLOCKED_PATTERNS,
} from '@akson/cortex-doc-standards';

const validator = createValidator('nextjs', {
  maxLines: 150,
  requiredSections: ['Custom Section'],
});

移徙清单

1. 更新导入 至上述统一出口.
2. 替换旧类型 (单位:千美元)ValidationRule, (中文(简体) ), DocumentationRules(等等)与 UnifiedRule。 。 。 .
3. 证据验证符 通过 UnifiedDocumentationValidator 或者说 createValidator()。 。 。 .
4. 合并配置 使用辅助工具,例如 mergeRules 财务报告和审定财务报表 getProjectRules。 。 。 .
5. 采用常见被屏蔽的模式 从 BASE_BLOCKED_PATTERNS 并且只在必要的时候才能延长.

import { getProjectRules, mergeRules } from '@akson/cortex-doc-standards';

const baseRules = getProjectRules('monorepo');
const rules: UnifiedRule = mergeRules({
  maxLines: 180,
  requiredSections: ['Usage'],
}, baseRules);

const validator = new UnifiedDocumentationValidator(rules);

规则系统参考

快速启动

# Initialize rules configuration
npx @akson/cortex-doc-standards rules init --name "MyProject" --type nextjs

# Generate CLAUDE.md (standalone generator works without a build step)
npx @akson/cortex-doc-standards generate-claude generate --dry-run

# Validate configuration
npx @akson/cortex-doc-standards rules validate

内建规则目录

项目模板自动构成规则集 :

• 下一个.js / 后端 –包括所有核心规则外加GitHub工作流程.
• 单曲 ——核心规则+共享一揽子治理.
• 小蝶/移动 - 安全+测试规则.
• 软件包/库 ——以出版指导为最低标准.
• 制作人Kit SaaS - 与所有 MakerKit 规则实现完整的框架整合.
• 横线 – MakerKit web + Flutter 有共享后端模式的移动.

配置图

{
  "projectName": "MyProject",
  "projectType": "nextjs",
  "rules": [
    {
      "id": "shared-packages",
      "enabled": true,
      "variables": {
        "packages.namespace": "@akson",
        "packages.registry": "https://registry.npmjs.org"
      },
      "overrides": {
        "title": "Custom Title",
        "append": "Additional custom content"
      }
    }
  ],
  "globalVariables": {
    "project.name": "MyProject",
    "project.type": "nextjs"
  }
}

CLI 参考

# Discover rules
npx @akson/cortex-doc-standards rules list

# Initialize with explicit output path
npx @akson/cortex-doc-standards rules init \
  --name "MyApp" \
  --type backend \
  --output ./docs/rules.json

# Generate CLAUDE.md from a custom config
npx @akson/cortex-doc-standards rules generate \
  --config ./docs/rules.json \
  --output ./CLAUDE.md

# Validate or augment an existing configuration
npx @akson/cortex-doc-standards rules add-rule --id security-standards --enabled
npx @akson/cortex-doc-standards rules validate --config ./docs/rules.json

高级使用

• 自定义变量 - 为模板提供项目特定数据.

  {
    "rules": [
      {
        "id": "testing-standards",
        "variables": {
          "test.unit": "vitest",
          "test.e2e": "playwright test",
          "coverage.unit": "90"
        }
      }
    ]
  }
  

• 规则覆盖 – 裁剪标题, 附加自定义注释, 或禁用区域, 而同时保留在统一计划内 .

• 工厂助手 – 说吧 – createValidator(projectType, overrides) 在验证前将默认与覆盖合并并解析变量.

const validator = createValidator('package', {
  blockedPatterns: [...BASE_BLOCKED_PATTERNS, 'My legacy phrase'],
});

const results = await validator.validate('./docs');

文件标准

这个软件包有助于在整个Cortex项目中执行一致的文档标准:

核心原则

• 清晰度 - 简明扼要的文件
• 一致性 - 标准化格式和命名
• 可维持性 - 基于规则的生成和验证
• AI 一体化 - Claude AI工作流程优化

MCP 服务器集成

软件包包括一个用于Claude AI集成的MCP(模式上下文协议)服务器:

启动 MCP 服务器

# Run the MCP server
npx cortex-doc-standards-mcp

可用的 MCP 工具

MCP 服务器提供了以下工具:

• 文件验证
• 规则管理
• 模板生成
• 标准执行

与克洛德合并

将 MCP 服务器添加到您的 Claude 配置中, 直接在 Claude 对话中访问文档工具 .

配置

该软件包使用简单的基于JSON的配置系统:

规则文件结构

{
  "version": "1.0.0",
  "rules": [
    // Your documentation rules here
  ],
  "templates": {
    // Template configurations
  }
}

类型脚本

interface RulesConfig {
  version: string;
  rules: DocumentationRule[];
  templates: Record<string, TemplateConfig>;
}

版本历史

• 3.0.0 (单位:千美元) - 现有CLI和MCP服务器版本
• 2.x.x (中文(简体) ) - 遗产版本

捐款

Cortex包生态系统的一部分. 欢迎捐款!

许可证

麻省理工学院

支助

如需支持,请在 Cortex 软件包仓库。 。 。 .