# Agent Guidelines

> Use when writing articles or developing full-stack code (frontend/Java/Go/Python/Redis/Kafka/MySQL/Spring Cloud/云原生) and you need AI collaboration behavioral guidelines — the four principles (align before acting, technical accuracy, surgical edits, verifiable delivery), the RIPER-5 coding workflow, monorepo testing rules, and authentic writing voice. Trigger on full-stack code tasks, the RIPER-5 development workflow, technical writing standards, or monorepo testing rules.

- Skill: `magebyte-zero/agent-guidelines` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add magebyte-zero/agent-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/magebyte-zero/agent-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: magebyte-zero (https://skillmd.com/u/magebyte-zero)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/magebyte-zero/agent-guidelines

---


# AI 协作行为准则

面向全栈开发的 AI 协作行为准则——覆盖**内容生产、全栈代码开发（前端/Java/Go/Python + 后端中间件/云原生）**。改编自 Andrej Karpathy 编码准则、GoMall 的 RIPER-5 协议、Cloudflare Workers SDK 的 Monorepo 测试规范、Dan Abramov 的"个人声音"原则，做了领域化重写。

核心不是"请写好代码/文章"，而是一组**面向真实场景的行为约束**，把四类常见失误收束为可执行原则：

1. **动笔前先对齐** — 不擅自假设，先确认任务类型 / 受众 / 平台 / 角度
2. **专业准确、克制发挥** — 不编造技术事实，版本与环境标注清楚，代码命令可运行
3. **精准改动、最小侵入** — 只改必须改的，不顺手重构无关代码或内容段落
4. **目标驱动、可验证交付** — 模糊指令变可验证目标，交付前用自检清单闭环

## When to Use

- 写技术内容：技术博客 / 社区文章 / 文档
- 写或改**全栈代码**：前端（React/Vue/Next.js）、Java/Spring、Go、Python、Redis/Kafka/MySQL/Spring Cloud/云原生
- 代码任务需要 RIPER-5 严谨工作流（多文件 / 生产代码）
- 改代码、改历史文章、做代码审查 / 重构
- 任何涉及技术准确性、生产代码、对外发布内容的任务

## 文件清单（按需读取）

| 文件 | 用途 | 何时读 |
|---|---|---|
| `CLAUDE.md` | Claude Code 项目规则（准则母版） | 在 Claude Code 中工作或要合并进项目 `CLAUDE.md` |
| `AGENTS.md` | Codex / 通用 Agent 执行版（含角色定位、禁止事项、输出要求） | 用 Codex 或其他 Agentic IDE |
| `CURSOR.md` + `.cursor/rules/agent-guidelines.mdc` | Cursor 自动应用规则 | 用 Cursor |
| `references/examples.md` | 全栈翻车场景 before/after（含 RIPER-5、Go/Python/前端翻车、提交信息机器人腔）+ 自检对照表 | 需要具体反例、做培训或 red-team 时 |

## 安装到项目

准则以多格式提供，可合并进任意项目根目录：

```bash
# Claude Code
cp CLAUDE.md /path/to/your-project/CLAUDE.md          # 新建
# 或追加： cat CLAUDE.md >> /path/to/your-project/CLAUDE.md

# Codex / 通用 Agent
cp AGENTS.md /path/to/your-project/AGENTS.md

# Cursor（自动应用）
mkdir -p /path/to/your-project/.cursor/rules
cp .cursor/rules/agent-guidelines.mdc /path/to/your-project/.cursor/rules/
```

合并时若项目已有 `CLAUDE.md` / `AGENTS.md`，把本准则的「四原则 + 领域规则 + 禁止事项」作为新章节追加，避免覆盖项目既有约定。

## 快速自检（交付前默念）

- [ ] 任务类型与范围已对齐（内容 or 代码模块/文件）
- [ ] 技术点准确、版本已标注、无编造（全栈各语言红线）
- [ ] 代码/命令可运行（或注明"未实测"）
- [ ] 代码任务走了 RIPER-5（多文件/生产代码应走；简单改动轻量）
- [ ] 改动精准、无顺手改写无关内容、未碰兄弟模块
- [ ] 符合写作规范、无机器人腔、务实不废话
- [ ] 给出验证（内容：标题备选/摘要/配图建议；代码：测试结果/影响说明）

> 完整版与反例见 `CLAUDE.md` 与 `references/examples.md`。本 SKILL.md 只做索引与触发，不重复准则全文。