policy-agent 是一个专注于 Rails 应用授权安全的技能，核心是使用 Pundit 创建清晰、安全且经过充分测试的授权策略。它适用于需要为 Rails 项目添加授权、限制访问、定义权限规则的场景。
用途 该技能的角色是 Pundit、授权与访问安全方面的专家，使命是创建清晰、安全、经过良好测试的策略。它始终在编写策略的同时编写 RSpec 测试，遵循最小权限原则（默认拒绝），并验证每个控制器动作都有对应的 authorize 调用。
技术栈与架构 项目技术栈为 Ruby 3.3、Rails 8.1 与 Pundit（授权）。涉及的目录包括：app/policies/（Pundit 策略，可创建和修改）、app/controllers/（控制器，可读取和审计）、app/models/（模型，可读取）、spec/policies/（策略测试，可创建和修改）、spec/support/pundit_matchers.rb（Pundit 的 RSpec 匹配器）。
主要能力 该技能提供以下命令能力：测试方面，可运行全部策略测试（bundle exec rspec spec/policies/）、特定策略测试、特定行测试以及带文档格式的详细输出；生成方面，可使用 bin/rails generate pundit:policy Entity 生成策略；代码检查方面，可对策略和测试运行 RuboCop 自动修正；审计方面，可搜索缺少 authorize 的控制器动作，并可通过 Rails 控制台手动测试策略。
边界与准则 始终要做：编写策略测试、默认拒绝、验证每个控制器动作都有 authorize。需要先询问：授予管理员级权限之前、修改现有策略之前。绝不要做：默认允许访问、跳过策略测试、硬编码用户 ID。
Rails 8 授权要点 作用域策略：对 index 动作使用 policy_scope。无头策略：对非模型动作使用 authorize :dashboard, :show?。允许属性：为强参数定义 permitted_attributes。
命名约定 策略文件位于 app/policies/，包括 application_policy.rb、entity_policy.rb、submission_policy.rb、item_policy.rb、user_policy.rb 等；测试文件位于 spec/policies/，与策略一一对应。
策略结构 每个策略都继承自 ApplicationPolicy，该基类默认拒绝所有动作。每个策略只实现它需要允许的动作。ApplicationPolicy 基类与 5 种策略模式在参考文档中提供：基础 CRUD 策略（基于所有者的访问与 permitted_attributes）、带角色的策略（作者/管理员/实体所有者角色层级与自定义动作）、带复杂逻辑的策略（作用域可见性、依赖检查）、带时间条件的策略（基于时间的约束，如预订窗口）、管理操作策略（带自我保护的管理员管理）。完整实现见 policy-patterns.md。
控制器授权关键模式 每个控制器动作都必须调用 authorize 或 policy_scope。例如 index 使用 policy_scope(Entity) 获取作用域集合；show 使用 authorize @entity 检查 show?；update 使用 authorize @entity 检查 update?，并通过 permitted_attributes(@entity) 更新。同时应在 ApplicationController 中始终捕获 Pundit::NotAuthorizedError，并设置 flash 提示与重定向。完整的控制器示例、自定义动作授权与视图策略检查见 testing-and-controllers.md。
测试 始终为每个策略编写策略测试，覆盖所有角色与边界情况。每个策略必需的测试上下文包括：未认证访客（user: nil）、普通已认证用户、资源所有者/作者、管理员（如适用）、自定义动作测试。测试结构示例使用 RSpec.describe EntityPolicy, type: :policy，并通过 forbid_action、permit_actions 等匹配器断言。完整的测试示例（包括基于角色的测试与时间条件测试）见 testing-and-controllers.md。
安全清单 每个控制器动作都有 authorize 或 policy_scope；策略遵循最小权限原则（默认拒绝）；测试覆盖所有角色与边界情况；作用域根据用户正确过滤数据；为更新定义了 permitted_attributes；测试了未认证访客（user: nil）；测试了管理员（如适用）；测试了自定义动作。
适用场景与限制 该技能适用于 Rails 8.1 项目中使用 Pundit 进行授权管理的开发场景，尤其是需要生成策略、编写策略测试、审计控制器授权覆盖情况的团队。其限制在于：它面向特定技术栈（Ruby 3.3、Rails 8.1、Pundit），不适用于其他语言或框架；关于收费、价格、平台等信息暂未提供。