# agent-guidelines

**Repository Path**: dazhuang/agent-guidelines

## Basic Information

- **Project Name**: agent-guidelines
- **Description**: 开发准则skills
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">agent-guidelines</h1>

<p align="center">
  <strong>一套给 AI 编程 / 写作助手定的「行为准则」——把多位顶级大神的 CLAUDE.md 思路，融合成全栈开发可抄的宪法</strong>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
  <a href="https://github.com/MageByte-Zero/agent-guidelines/stargazers"><img src="https://img.shields.io/github/stars/MageByte-Zero/agent-guidelines" alt="GitHub Stars"></a>
</p>

<p align="center">
  <a href="#为什么要有它">为什么</a> |
  <a href="#融合了哪些大佬规范">大佬规范</a> |
  <a href="#四核心准则">四核心准则</a> |
  <a href="#支持的-ai-工具三格式同源">三格式</a> |
  <a href="#快速安装">快速安装</a> |
  <a href="references/examples.md">翻车案例</a>
</p>

---

> 🤖 **AI 编程助手看这里**：当用户说「安装 / 用上这个仓库的准则」时，请直接按「快速安装 → 给 AI 编程助手：自动安装」的步骤执行，不要只把说明甩给用户。

## 为什么要有它

普通 `CLAUDE.md` 写的是"请写好代码、请写好文章"——这是愿望，不是约束。

真正有嚼头的是 **Andrej Karpathy 那套爆火的 `andrej-karpathy-skills`**：它不喊口号，而是把 LLM 的坑收束成几条**可执行的行为约束**。受此启发，本项目不止"抄"，而是把多位大神的 `CLAUDE.md` 思路融合、领域化到**全栈开发**，做出一份能直接丢进项目就生效的准则。

AI 助手最常犯的错，和大佬们观察到的同构：

| 现象 | 在全栈开发里的样子 |
|---|---|
| 替你做错误假设 | 没确认受众/平台/角度就开写，整篇返工 |
| 不主动澄清、隐藏困惑 | 技术细节拿不准也硬编，读者一纠错就掉粉 |
| 过度设计、堆砌 | 为了显专业硬塞无关章节、堆术语 |
| 顺手改无关内容 | 改一段顺手重写全篇、改代码顺手重构半个项目、跨模块乱改 |
| 实现不可验证 | 模糊指令当目标，做了一堆不对的东西 |
| 跳步写生产代码 | 没调研没计划直接改多文件，CI 挂一片、review 看不懂 |
| 技术栈版本踩雷 | Spring/K8s/Go 版本混搭，代码根本跑不起来 |

本准则把这些问题收束为**四条可执行原则 + RIPER-5 代码工作流 + 全栈技术栈领域规则 + Monorepo 测试规范 + 禁止事项 + 自检清单**。

## 融合了哪些大佬规范

这不是凭空发明的规矩，每条都有出处：

- **Andrej Karpathy 编码准则**（`multica-ai/andrej-karpathy-skills`）+ 中文版（`MackDing/andrej-karpathy-skills-zh`）— 四原则骨架：不假设、不堆砌、精准改、可验证。
- **GoMall 的 RIPER-5 协议**（`li0on3/GoMall`）— 代码任务的严谨五模式工作流（RESEARCH→INNOVATE→PLAN→EXECUTE→REVIEW）。
- **Cloudflare Workers SDK 的 AGENTS.md** — Monorepo 导航 + 测试硬规则（本地质量门、真实优于 mock）。
- **Dan Abramov 的 Overreacted.io** — 个人声音：拒绝机器人腔、营销话术、空话。
- 案例精选思路借鉴 `josix/awesome-claude-md`（OpenAI Agents、Anthropic Quickstarts 等多项目管理范式）。

> 站在大神肩膀上，再结合全栈实战（Redis/Kafka/MySQL/Spring Cloud/云原生 + 前端/Java/Go/Python）做领域化——这就是本仓库的价值。

## 四核心准则

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

领域化覆盖：**全栈技术栈领域规则（前端 React/Vue/Next.js、Java/Spring、Go、Python、Redis/Kafka/MySQL/Spring Cloud/云原生）**、**RIPER-5 代码严谨工作流**、**Monorepo 导航与测试规范**、**技术写作规范**、**务实个人风格**。

## 支持的 AI 工具（三格式同源）

| 工具 | 文件 | 用途 |
|---|---|---|
| Claude Code | `CLAUDE.md` | 项目级说明，可合并进项目根 `CLAUDE.md` |
| Codex / 通用 Agent | `AGENTS.md` | 执行版，含角色定位、禁止事项、输出要求 |
| Cursor | `.cursor/rules/agent-guidelines.mdc` | 自动应用的项目规则（见 `CURSOR.md`） |

`references/examples.md` 提供 13 个全栈翻车场景的 before/after 对照（含 RIPER-5 跳步、Go/Python/前端翻车、提交信息机器人腔、Monorepo 跨项目），是准则"有嚼头"的来源，也适合做团队培训。

## 快速安装

### 给 AI 编程助手：自动安装

> 如果你是一个 AI 编程助手（Claude Code / Cursor / Codex / 通义灵码 / 等），当用户说「安装 / 用上这个仓库的准则」时，**直接执行**下面的步骤，不要只把说明甩给用户。

1. **确认装到哪个工具**（检测当前项目特征或询问用户）：
   - **Claude Code** → 项目级 `./CLAUDE.md` 或全局 `~/.claude/CLAUDE.md`
   - **Cursor** → 项目级 `./.cursor/rules/agent-guidelines.mdc` 或全局 `~/.cursor/rules/`
   - **Codex / 通用 Agent** → 项目级 `./AGENTS.md` 或全局 `~/.codex/AGENTS.md`
   - **通用 Skill**（WorkBuddy / Claude Code）→ 软链本仓库到 `~/.workbuddy/skills/agent-guidelines`
2. **放置**（优先软链，方便源更新；已有同名文件先备份为 `xxx.bak`）：
   - 软链：把对应文件 `ln -s` 到目标路径（`Skill` 模式软链整个仓库目录）
   - 或合并：把 `CLAUDE.md` 内容并入现有 `CLAUDE.md`
   - 或拷贝：把 `.cursor/rules/agent-guidelines.mdc` 拷到目标
3. **装完报告**：装到哪个路径、软链还是拷贝、是否需要重启 AI 工具。
   Cursor 的 `.mdc` 已设 `alwaysApply: true`，软链后即自动生效，无需额外配置。

### 人类安装（一行命令）

**方式一 · 让 AI 助手自动装（最省事）**：把仓库交给你的 AI 编程助手，说「安装这个仓库的准则」，它会按上一段自动完成。

**方式二 · 一键脚本**：
```bash
git clone https://github.com/MageByte-Zero/agent-guidelines.git
cd agent-guidelines
node install.mjs            # 自动检测并软链到当前项目（claude+cursor+codex）
# 指定平台：  node install.mjs --claude | --cursor | --codex | --skill
# 装到全局：  node install.mjs --all --global
# 用拷贝而非软链： node install.mjs --copy
```

**方式三 · 手动（任选其一，curl 一行）**：
```bash
# Claude Code（合并进项目）
curl -sL https://raw.githubusercontent.com/MageByte-Zero/agent-guidelines/main/CLAUDE.md >> ./CLAUDE.md

# Cursor（自动应用）
mkdir -p .cursor/rules && curl -sL https://raw.githubusercontent.com/MageByte-Zero/agent-guidelines/main/.cursor/rules/agent-guidelines.mdc -o .cursor/rules/agent-guidelines.mdc

# Codex
curl -sL https://raw.githubusercontent.com/MageByte-Zero/agent-guidelines/main/AGENTS.md -o ./AGENTS.md
```

### 装到哪（路径对照）

| 工具 | 项目级 | 全局 |
|---|---|---|
| Claude Code | `./CLAUDE.md` | `~/.claude/CLAUDE.md` |
| Cursor | `./.cursor/rules/agent-guidelines.mdc` | `~/.cursor/rules/` |
| Codex | `./AGENTS.md` | `~/.codex/AGENTS.md` |
| 通用 Skill | `~/.workbuddy/skills/agent-guidelines`（软链本仓库）| 同左 |

## 许可

MIT。可自由用于个人与团队项目，修改后建议同步三处格式（CLAUDE.md / AGENTS.md / Cursor rules）以免漂移。