CLI 编程 Agent 通用方法论

概述

本文档介绍 AI 编程 Agent（尤其是 CLI 形态）的四大核心方法论：权限 (Permissions)、技能 (Skills)、规则 (Rules)、文档 (Documentation)。这些方法论在 Claude Code、Qoder、CodeBuddy Code 等 CLI 工具中均有对应实现，是高效、安全使用 AI 编程的基础。

权限 (Permissions)

为什么需要权限

AI Agent 拥有执行命令、读写文件的能力，一旦误操作（如删除文件、推送代码、泄露密钥）会造成严重后果。权限体系用于约束 Agent 的行为边界。

权限模型

大多数 CLI Agent 采用三态权限模型：

状态	含义	适用场景
allow	自动允许，无需询问	高频、低风险操作（如 `npm test`、读源码）
ask	每次询问用户	中等风险操作（如修改配置文件）
deny	自动拒绝	危险/敏感操作（如 `rm -rf`、读密钥文件）

权限配置最佳实践

1. 白名单优先，黑名单兜底

json

{
  "permissions": {
    "allow": [
      "Read(./src/**)",
      "Bash(npm test)",
      "Bash(mvn test)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)",
      "Read(./.env)",
      "Read(./**/*.pem)",
      "Read(./**/*.key)"
    ]
  }
}

2. 敏感文件永远 deny

json

{
  "deny": [
    "Read(.env)",
    "Read(.env.*)",
    "Read(**/*.pem)",
    "Read(**/*.key)",
    "Read(**/id_rsa)",
    "Read(**/credentials.json)"
  ]
}

3. 危险命令永远 deny

json

{
  "deny": [
    "Bash(rm -rf /*)",
    "Bash(git push --force *)",
    "Bash(git reset --hard *)",
    "Bash(drop table *)",
    "Bash(docker rm -f $(docker ps -aq))"
  ]
}

4. 分层配置

层级	作用	示例
全局	个人通用安全规则	永远 deny 密钥文件
项目共享	团队约定	allow 项目测试命令
项目本地	个人偏好	额外 allow 个人常用命令

权限模式

默认模式：按规则自动判断
只读模式 (plan)：只允许读，不允许写/执行
自动接受模式：自动接受文件编辑
跳过权限：完全放权（生产环境禁用）

各工具的权限命令对比

工具	权限配置方式
Claude Code	`settings.json` 的 `permissions` 字段、`/permissions` 命令
Qoder	`--allowed-tools` / `--disallowed-tools` 参数、`--yolo` 跳过
CodeBuddy Code	`settings.json`、交互式授权确认

技能 (Skills)

什么是技能

技能（Skills）是封装可复用领域能力的模块，将特定任务的知识 + 流程 + 工具打包，供 Agent 按需调用。相比每次用提示词描述，技能可以一次定义、多次复用。

技能的价值

复用：复杂流程封装一次，团队共享
一致性：确保同类任务按相同标准执行
降本：减少重复上下文，节省 Token
专业化：注入领域知识，提升任务质量

技能结构

典型技能包含：

skills/
├── <skill-name>/
│   ├── SKILL.md          # 技能定义（触发条件、说明、流程）
│   └── scripts/          # 可选的辅助脚本
│       └── helper.sh

技能定义要素

markdown

---
name: deploy-service          # 技能名称
description: 部署微服务到 k8s 集群，触发条件...  # 何时使用
---

# 技能内容

## 前置条件
- kubectl 已配置
- 有集群操作权限

## 执行流程
1. 构建镜像
2. 推送镜像仓库
3. 更新 deployment
4. 验证滚动更新状态

## 注意事项
- 生产环境需先备份旧版本

适合封装为技能的场景

场景	示例
重复性运维流程	部署、回滚、备份
项目特定规范	代码生成模板、提交规范
多步骤调试流程	日志分析、性能诊断
领域知识	特定框架的配置方法

本项目的技能示例

结合本项目结构，可封装：

部署技能：docker-compose / helm / k8s / nomad / serverless-fc 各部署方式的封装
规则加载技能：按任务自动加载 rule/ 目录下对应模块
CRUD 生成技能：按 rule/03-crud-template.md 生成标准 CRUD

规则 (Rules)

什么是规则

规则（Rules）是持久化的约束性指令，告诉 AI 应该怎么做、不能怎么做。规则文件在每次会话自动加载，确保 AI 行为符合项目约定。

规则文件对比

工具	规则文件	说明
Claude Code	`CLAUDE.md`	项目/全局记忆文件
Qoder	`AGENTS.md`	项目记忆文件
CodeBuddy	`AGENTS.md`	项目规则
Cursor	`.cursorrules` / `.cursor/rules/*.mdc`	项目规则
通用	`.github/copilot-instructions.md`	GitHub Copilot 规则

规则的内容类型

1. 编码规范

markdown

## 编码规范
- 遵循阿里巴巴 Java 开发手册
- 类名使用大驼峰，方法名使用小驼峰
- 统一使用 ResultUtilSimpleImpl 返回结果

2. 架构约定

markdown

## 架构约定
- 四层架构：Controller -> Service -> Manager -> Mapper
- 各模块职责单一，禁止跨层调用
- 禁止 Service 直接操作 Mapper

3. 技术栈约束

markdown

## 技术栈
- Java 17 + Spring Boot 3.x
- 必须使用 Maven 构建，禁止引入 Gradle
- 数据库使用 MySQL 8.x

4. 安全红线

markdown

## 安全红线
- 禁止硬编码密码、密钥、Token
- 禁止 SQL 拼接，必须使用参数化查询
- 敏感信息使用配置中心管理

规则设计原则

具体：避免"写好代码"这种空话，给出可执行的判断标准
分层：全局规则（个人习惯）+ 项目规则（团队约定）分离
精简：规则太多会被稀释，聚焦核心约束
可验证：规则应能被检查（如"必须添加 @Valid 注解"）

本项目规则体系

本项目的 rule/ 目录采用模块化规则方案：

rule/
├── index.md                    # 规则索引与切换机制
├── 01-project-structure.md     # 项目结构规范
├── 02-dependency-config.md     # 依赖配置规范
├── 03-crud-template.md         # CRUD 模板规范
├── 04-component-integration.md # 组件集成规范
├── 05-validation.md            # 参数验证规范
├── 06-swagger.md               # Swagger 规范
└── structure-projects-rule.md  # 完整版规则（B方案）

使用时按任务类型加载对应模块，复杂任务自动升级到完整版。

文档 (Documentation)

什么是"文档"方法论

在 AI Agent 语境下，文档方法论指的是维护 AI 可读的上下文知识，让 Agent 持续了解项目状态、约定和历史决策。

文档类型

1. 记忆文件 (Memory)

持久化项目背景，每次会话自动加载：

markdown

# CLAUDE.md / AGENTS.md

## 项目背景
本项目是 XXX 云平台，采用微服务架构...

## 关键决策
- 2026-08 决定从 docker-compose 迁移到 k8s
- 统一中心目录命名为 structure-xxx-center 格式

2. 规范文档 (Rules)

编码规范、架构约定，见规则章节。

3. 操作手册 (Runbook)

可复用的操作流程，如本站「开发环境」章节下的 Go、Node.js、JDK/Maven 等环境配置指南。

4. 变更记录

让 AI 了解"为什么这么做"，而非仅仅"做了什么"：

markdown

## 变更记录
- 2026-08-15：IAM 应用层新增部署文件
- 2026-08-13：统一中心目录命名格式

文档维护原则

随代码更新：文档与代码同步演进，避免过期
AI 友好：结构化、可搜索、可被 Agent 直接读取
单一事实源：同一信息只维护一处，避免冲突
记录"为什么"：决策背景比结果更有价值

文档与 Agent 协作流程

1. 编写规则/记忆文件 → 定义 Agent 行为边界
2. Agent 读取文档 → 理解项目上下文
3. Agent 执行任务 → 遵循规则约束
4. 更新文档 → 沉淀新知识
5. 下次会话复用 → 形成正向循环

提示词方法论

高质量提示词结构

[角色] + [任务] + [上下文] + [约束] + [期望输出]

示例：

markdown

你是一位 Java 后端工程师（角色）。

请为 User 模块新增一个分页查询接口（任务）。

技术栈：Spring Boot 3 + MyBatis-Plus，参考现有 ContentController 的写法（上下文）。

约束：
- 遵循 rule/03-crud-template.md 的模板
- 使用 ResultUtilSimpleImpl 返回
- 添加参数校验注解（约束）

输出：完整代码 + 简要说明（期望输出）。

提示词技巧

技巧	说明	示例
明确边界	说明做什么、不做什么	"只改 Service 层，不动 Controller"
提供参照	引用现有实现	"参考 XxxServiceImpl 的写法"
分步执行	复杂任务拆解	"先建实体类，再写 Mapper"
要求验证	让 AI 自测	"完成后运行测试并报告结果"

上下文管理

上下文的重要性

Agent 的上下文窗口有限且成本与质量相关。良好的上下文管理能：

提升响应质量（减少无关信息干扰）
降低成本（减少 Token 消耗）
避免幻觉（提供准确上下文）

上下文管理策略

精准引用：只提供相关文件，而非整个项目
及时清理：长会话定期清空/压缩
善用记忆：把稳定信息写入记忆文件，而非每次在对话中重复
模块化规则：按需加载规则模块，而非一次性加载全部
子代理隔离：独立任务用子代理处理，避免污染主上下文

上下文分层

层级	内容	加载时机
全局记忆	个人习惯、通用规范	每次会话
项目记忆	项目架构、约定	每次会话
任务规则	特定任务规范	按需加载
对话上下文	当前任务细节	会话中累积

CLI 编程 Agent 通用方法论 ​

概述 ​

目录 ​

权限 (Permissions) ​

为什么需要权限 ​

权限模型 ​

权限配置最佳实践 ​

1. 白名单优先，黑名单兜底 ​

2. 敏感文件永远 deny ​

3. 危险命令永远 deny ​

4. 分层配置 ​

权限模式 ​

各工具的权限命令对比 ​

技能 (Skills) ​

什么是技能 ​

技能的价值 ​

技能结构 ​

技能定义要素 ​

适合封装为技能的场景 ​

本项目的技能示例 ​

规则 (Rules) ​

什么是规则 ​

规则文件对比 ​

规则的内容类型 ​

1. 编码规范 ​

2. 架构约定 ​

3. 技术栈约束 ​

4. 安全红线 ​

规则设计原则 ​

本项目规则体系 ​

文档 (Documentation) ​

什么是"文档"方法论 ​

文档类型 ​

1. 记忆文件 (Memory) ​

2. 规范文档 (Rules) ​

3. 操作手册 (Runbook) ​

4. 变更记录 ​

文档维护原则 ​

文档与 Agent 协作流程 ​

提示词方法论 ​

高质量提示词结构 ​

提示词技巧 ​

上下文管理 ​

上下文的重要性 ​

上下文管理策略 ​

上下文分层 ​

CLI 编程 Agent 通用方法论

概述

目录

权限 (Permissions)

为什么需要权限

权限模型

权限配置最佳实践

1. 白名单优先，黑名单兜底

2. 敏感文件永远 deny

3. 危险命令永远 deny

4. 分层配置

权限模式

各工具的权限命令对比

技能 (Skills)

什么是技能

技能的价值

技能结构

技能定义要素

适合封装为技能的场景

本项目的技能示例

规则 (Rules)

什么是规则

规则文件对比

规则的内容类型

1. 编码规范

2. 架构约定

3. 技术栈约束

4. 安全红线

规则设计原则

本项目规则体系

文档 (Documentation)

什么是"文档"方法论

文档类型

1. 记忆文件 (Memory)

2. 规范文档 (Rules)

3. 操作手册 (Runbook)

4. 变更记录

文档维护原则

文档与 Agent 协作流程

提示词方法论

高质量提示词结构

提示词技巧

上下文管理

上下文的重要性

上下文管理策略

上下文分层