agent-guidelines

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

为什么 | 大佬规范 | 四核心准则 | 三格式 | 快速安装 | 翻车案例

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

为什么要有它

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

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

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

本准则把这些问题收束为四条可执行原则 + 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 工具（三格式同源）

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 编程助手，说「安装这个仓库的准则」，它会按上一段自动完成。

方式二 · 一键脚本：

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 一行）：

# 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

装到哪（路径对照）

许可

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