ameba-configuration（Ameba配置Skill）Skill 是什么？如何配置 Crystal 代码检查？

Ameba配置Skill：让 Crystal 项目的静态代码检查配置一次到位

专治「配置难写」：.ameba.yml 规则上百条、类别多、严重级别难拿捏，这个技能把配置工作从「翻文档 + 试错」变成「说清需求 + 拿到可用配置」。
覆盖完整配置面：源文件范围（Globs）、排除项（Excluded）、Lint / Style / Performance 三大规则类别、严重级别（Error / Warning / Convention）、内联禁用，都能一次生成。
开箱有三档模板：宽松（新项目）、平衡（大多数项目）、严格（生产代码），配合渐进式收紧策略，避免一上来就被技术债淹没。
落地建议成体系：从「先生成默认配置再裁剪」到「用版本控制共享配置」「排除生成代码」，附带常见陷阱清单，团队可以直接照抄。
零学习成本的调用方式：不需要额外记命令，描述项目类型和目标，技能会读取你的工程文件并产出 YAML 配置与修改建议。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

这个技能的中文名是 Ameba配置Skill，英文名 ameba-configuration，技能 ID 为 13890。

它要解决的问题非常具体：Ameba 是 Crystal 语言的静态代码分析工具，能强制统一代码风格、捕捉代码异味和错误构造、为很多问题提供自动修正。但它的能力全部依赖一份 .ameba.yml——规则分 Lint（正确性）、Style（代码约定）、Performance（性能）三大类，每条规则还有 Enabled、Severity、以及规则专属参数（比如 Style/LargeNumbers 的 IntMinDigits、Lint/UnusedArgument 的 IgnoreParameterNames）。手工配置时，开发者往往陷入三个困境：不知道有哪些规则、不知道严重级别怎么分层、不知道排除哪些目录才不会误伤。这个技能就是把这份配置工作交给 AI 来完成。

「一键安装」AI 技能提升效率的思路

前置条件：你已在使用支持 Skill 机制的 AI 客户端（例如具备技能市场/插件市场的 AI 编程助手，具体入口以官方说明为准）；本地有一个 Crystal 项目，并且已经引入 Ameba 作为开发依赖（Ameba 的引入方式请参照 Ameba 官方文档，以官方说明为准）。
安装入口：在客户端的技能市场或插件市场搜索技能名 ameba-configuration 或「Ameba配置Skill」，点击安装/启用即可；也可以按客户端支持的方式从技能配置文件导入（具体路径与命令以官方说明为准）。
验证是否生效：安装后在会话里直接提问，例如「帮我看看当前项目的 .ameba.yml 配置是否合理」。如果技能生效，它会使用其允许的工具（读取文件、执行命令）去定位并读取 .ameba.yml，或者在你要求时执行 ameba --gen-config 生成配置作为基线，再给出结论。若它完全不提配置文件、只做泛泛而谈，说明技能未启用。
首次试跑建议：先在一个分支上让技能生成配置，再本地执行一次 ameba 观察输出，确认没有大面积误报后再提交，避免影响团队 CI。

需要说明的是，这个技能标记为「用户可调用：false」，也就是它更适合被 AI 在需要时自动调度，而不是当作一个独立的命令行程序去执行。使用时你只需要用自然语言描述需求，配置产物由 AI 输出。

该技能的主要功能和特点

生成默认配置基线：能引导或执行 ameba --gen-config，生成包含全部可用规则及默认值的 .ameba.yml，让「有哪些规则」这件事从不可知变成可见。
编写源文件范围配置：按 Globs 定义要分析的文件（**/*.cr、**/*.ecr），用 !lib 排除依赖，并针对标准 Web 应用、库/Shard、单体仓库三类项目给出不同的范围模板。
细粒度排除：通过 Excluded 全局排除生成代码、遗留代码、测试夹具、数据库迁移等不该做风格检查的目录，且优先推荐「排除具体文件/目录」而不是「全局禁用规则」。
三大规则类别按需配置：Lint 类关注正确性（未使用参数、无用赋值、变量遮蔽、不可达代码、语法问题、空块、调试器语句）；Style 类关注约定（常量名、方法名、类型名、谓词方法、冗余 return/begin、大数字下划线、条件括号、字符串字面量、变量命名）；Performance 类关注低效模式（any? 与 empty?、过滤后再取 size、map 后 compact、map 后 flatten）。
严重级别分层设计：把 Error / Warning / Convention 三档与「保守（CI 友好）」「严格（全量强制）」「渐进（先警告后升级为错误）」三种策略对应起来，帮助团队决定什么该阻断构建。
支持规则级定制参数：例如为 Lint/UnusedArgument 配置 IgnoreParameterNames 忽略下划线前缀参数，为 Performance/SizeAfterFilter 追加 FilterNames，为单条规则配置 Excluded 文件列表。
内联禁用建议与治理：能写出 # ameba:disable Style/LargeNumbers 这类单行禁用、块级禁用、类别级禁用，并强调「具体、临时、成对恢复」的最佳实践，避免注释满天飞。
附带最佳实践与陷阱清单：包括初始别太严格、排除别太宽、严重级别别错配、配置必须进版本控制、别忽略升级带来的规则改名、别忘了把 **/*.ecr 和 spec/**/*.cr 纳入范围等。

和「自己翻文档手写 YAML」相比，它的优势不在于知道某条规则，而在于成体系地给出与你项目形态匹配的一整套配置决策，并说清每个决定背后的权衡。

如何使用该技能？

第 1 步：描述你的项目形态。 说清楚是 Web 应用、库/Shard，还是单体仓库；有没有 ECR 模板文件、有没有遗留代码目录、有没有自动生成的代码。示例输入：

这是一个 Crystal Web 应用，源码在 src/，测试在 spec/，有 ECR 模板，src/legacy 是正在重构的老代码，spec/fixtures 是测试数据。帮我生成一份平衡档的 .ameba.yml。

第 2 步：让技能产出配置。 技能会使用读取能力检查现有 .ameba.yml（若有），必要时执行 ameba --gen-config 拿到默认配置，再按你的要求裁剪。典型输出结构如下（示意，实际内容以技能生成为准）：

Globs:
  - "**/*.cr"
  - "**/*.ecr"
  - "!lib"

Excluded:
  - src/legacy/**
  - spec/fixtures/**

Lint/Syntax:
  Enabled: true
  Severity: Error

Lint/UnusedArgument:
  Enabled: true
  Severity: Warning

Style/RedundantReturn:
  Enabled: true
  Severity: Convention

Style/LargeNumbers:
  Enabled: true
  Severity: Convention
  IntMinDigits: 5

Performance/AnyInsteadOfEmpty:
  Enabled: true
  Severity: Warning

第 3 步：按严重级别做分层决策。 直接提问：「哪些规则该设为 Error 阻断 CI，哪些设 Warning，哪些只做 Convention？」技能会给出保守/严格/渐进三种策略，并推荐把 Lint/Syntax、Lint/UnreachableCode 之类阻断性问题设为 Error，风格类先设 Warning 或 Convention。

第 4 步：处理例外与误报。 对确实无法修复的地方，要求它给出内联写法与范围控制，例如：

# 此 API 要求精确数字格式
# ameba:disable Style/LargeNumbers
LEGACY_TIMESTAMP = 1483859302
# ameba:enable Style/LargeNumbers

第 5 步：验证并纳入版本控制。 在本地运行 ameba 确认没有大面积误报，把 .ameba.yml 提交进仓库，让团队成员共享同一套配置。之后每次升级 Ameba 版本，再让技能复核一遍规则名和行为变更。

第 6 步：持续迭代。 定期把已清理干净的 Warning 升级为 Error，把已清理完的 Convention 升级为 Warning，形成「渐进收紧」的节奏。

同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
Ameba配置Skill（ameba-configuration）	AI 驱动的 Ameba 配置顾问	生成/裁剪 `.ameba.yml`、规则分级、排除策略、内联禁用治理、最佳实践清单	在支持 Skill 的 AI 客户端中启用即可；需项目已有 Ameba	首次接入 Ameba、团队统一标准、CI 严重级别分层、配置迁移	优势：懂项目形态、给整套决策而非单条规则；不足：不替代 Ameba 本体，产物仍需本地执行验证
手写 `.ameba.yml`（原生方式）	官方原生配置	完全自由地配置所有规则与参数	零安装，但需要通读官方文档，理解每条规则的键名与参数	规则已稳定、只做小幅调整的成熟项目	优势：完全可控、无额外依赖；不足：学习曲线陡，容易漏配 ECR 文件或测试目录，严重级别常配错
RuboCop（Ruby 生态静态分析工具）	跨语言的同类参照物	规则数量庞大、风格与安全检查齐全、可自动修正	需引入对应 Ruby 依赖	Ruby 项目；可作为理解「静态分析配置该怎么分层」的参照	优势：生态成熟、社区规则丰富；不足：与 Crystal 无关，不能直接用于 Crystal 项目
crystal tool format（Crystal 内置格式化器）	格式化工具	统一缩进、换行等排版格式	Crystal 自带，无需额外安装	排版统一	优势：零配置、无争议；不足：只管格式不管语义，与 Ameba 部分风格规则可能冲突，需避免重复启用

选择建议：排版交给 crystal tool format，语义与规则配置交给 Ameba，而「Ameba 的配置怎么定」这类决策工作，正是 Ameba配置Skill 的用武之地。

该技能的典型应用场景与实际体验情况

场景一：新 Crystal 项目初始化。 角色是刚接手项目的开发者，痛点是「不知道该开哪些规则，全开又怕红一片」。使用方式是描述项目类型，要求生成最小配置或标准配置。实际体验上，上手难度极低，几分钟内就能拿到一份可直接提交的配置；注意点是新项目也别图省事直接复制「严格档」，可以先从标准档起步，等团队适应再收紧。

场景二：老项目渐进式接入 Ameba。 角色是技术负责人，痛点是遗留代码大量报警，一旦全量设为 Error 会立刻卡死 CI。使用方式是要求「渐进档」，把遗留目录放进 Excluded，其余规则先用 Warning/Convention。实际体验上，这套「先警告后错误」的路径非常顺滑，能明显减少团队抵触；注意点是排除范围不能太宽，否则会失去静态分析的意义。

场景三：CI/CD 中的严重级别分层。 角色是负责流水线的工程师，痛点是「到底哪些问题该卡构建」。使用方式是把 CI 目标告诉技能，让它输出 Error/Warning/Convention 的分配方案并说明理由。实际体验上，输出的分层逻辑清晰、可直接落地；注意点是务必在提交前本地跑一次 ameba，确认本地与 CI 环境行为一致。

场景四：单体仓库与生成代码治理。 角色是维护多包仓库的工程师，痛点是 apps/**/src/**/*.cr、packages/**/src/**/*.cr 混杂，node_modules 和生成代码被误扫。使用方式是按「单体仓库模板」配置 Globs 与 Excluded。实际体验上，范围配置一次到位，分析时间明显更可控；注意点是生成代码目录一定要显式排除，否则会收获大量无意义告警。

该技能能为用户带来的价值

把「查文档的时间」变成「做决策的时间」。 Ameba 的规则横跨三大类别、每条还带专属参数，从零开始啃文档通常以小时计；而技能能在一次对话内产出可用配置，把节省下来的时间用在真正需要判断的地方——比如某条规则在当前代码库里是否值得启用。

降低静态分析工具的落地门槛。 很多团队放弃 Ameba 不是因为工具不好，而是因为配置太难、一上来就报警一片。技能给出的「宽松 → 平衡 → 严格」三档路径和渐进式严重级别策略，让接入变成一个可控的、分阶段的过程，而不是一次性的硬切换。

让团队标准可共享、可演进。 通过把 .ameba.yml 纳入版本控制，并配合「定期审查配置」「升级后复核规则变更」的建议，代码质量标准从口头约定变成了仓库里的一个文件，新成员拉下代码即自动对齐。

长期收益是可累积的。 每清理掉一类 Warning 就把它升级为 Error，技术债被一档一档地消化掉；Performance 类规则（如 count 替代「过滤后取 size」、compact_map 替代「map 后 compact」）还能在代码合入前就拦下低效写法，减少后期性能排查成本。

常见问题 FAQ

Q1：这个技能怎么安装？需要额外付费吗？ 在支持 Skill 机制的 AI 客户端中，通过技能市场或插件市场搜索 ameba-configuration / 「Ameba配置Skill」启用即可，具体入口与路径以官方说明为准；也有客户端支持以配置文件方式导入。收费情况取决于你所使用的 AI 客户端本身，各平台政策不同，以官方说明为准。

Q2：装了技能，是不是就不用装 Ameba 了？ 不是。技能负责的是「配置怎么写」这类顾问型工作，它本身不做代码分析。你仍然需要在 Crystal 项目中引入 Ameba（参照 Ameba 官方文档，以官方说明为准），配置写好后由 Ameba 本体执行检查、给出问题并自动修正。

Q3：适合谁用？纯新手可以用吗？ 最适合三类人：刚给 Crystal 项目接入 Ameba、需要快速搭出一份靠谱配置的开发者；需要在 CI 里划分严重级别、让团队统一标准的负责人；以及维护单体仓库、需要精细配置扫描范围与排除项的工程师。纯新手也能用，但建议按技能推荐的最佳实践「先生成默认配置再裁剪」，并在本地跑一次 ameba 看真实效果。

Q4：配置生成后 CI 报了一大堆问题怎么办？ 这是典型的「初始太严格」陷阱。处理方式是：把遗留代码、生成代码、测试夹具目录加入 Excluded，把风格类规则由 Error 降为 Warning 或 Convention，等清理干净后再逐步升级。另外注意不要用 Excluded: ["**/*"] 这种大范围排除，那等于关掉了静态分析本身。

Q5：和 crystal tool format、RuboCop 相比该怎么选？ 三者定位不同，不冲突。crystal tool format 只做排版格式化，零配置、无争议，继续用它；Ameba 负责语义级别的正确性、约定与性能检查，二者搭配使用，但要注意避免启用与格式化器冲突的风格规则。RuboCop 是 Ruby 生态的工具，不能直接用于 Crystal 项目，更多是作为「静态分析配置该如何分层」的参考。