Content
# ▲ AI Development Rules & Security Protocol Template
[English] · [中文](README_CN.md) · [日本語](README_JA.md)
> A universal, auditable, cross-tool ruleset for AI coding assistants. `AGENTS.md` is the single source of truth, automatically synced into the dedicated config files of Claude Code, Cursor, GitHub Copilot, Trae, OpenCode, Qoder, and other mainstream tools.
---
## What this repository is
This repository solves one concrete problem: **a single project is often used alternately by multiple AI coding tools** — you use Trae on the desktop, Cursor inside the IDE, Copilot on GitHub, and Claude Code in the terminal. If each tool reads its own rules, you get fragmentation where "Copilot knows a constraint that Claude doesn't," and AI behavior becomes inconsistent across tools.
It centralizes all development iron rules, prompts, sub-role definitions, and skill lists into one `AGENTS.md`, then uses a sync script to generate the config files each tool can read directly. Change once, apply everywhere.
Core features:
- **Single source of truth**: Only `AGENTS.md` is maintained; the rest are generated by `scripts/sync_rules.py`, never edited by hand.
- **Cross-tool fidelity**: GitHub Copilot does not support `@` imports, so the script **inlines** referenced files, ensuring every tool gets the full rules instead of dangling references.
- **Restricted skill acquisition**: A built-in 5-tier progressive skill acquisition protocol (standard library → package manager → local registry → preferred vendor official repos → restricted autonomous search) prevents AI from arbitrarily pulling unknown scripts from the web.
- **MCP red line**: MCP involves long-running processes and permissions; **AI is absolutely forbidden from self-downloading, self-installing, self-starting, or self-configuring** MCP — only you can configure it manually in each tool.
## Compatibility matrix
| Tool | File read | Sync method |
| --- | --- | --- |
| OpenAI Codex | `AGENTS.md` | Native |
| Cursor | `AGENTS.md` / `.cursor/rules/` | Native `AGENTS.md` |
| Claude Code | `CLAUDE.md` | Synced from this repo |
| GitHub Copilot | `.github/copilot-instructions.md` | Synced from this repo (Copilot now officially supports `AGENTS.md`; kept for compatibility) |
| Gemini CLI | `GEMINI.md` | Synced from this repo |
| Trae | `AGENTS.md` | Auto-injected into conversation |
| OpenCode / Qoder / Windsurf / Aider / RooCode | `AGENTS.md` or corresponding rules file | Most already natively support `AGENTS.md` |
## File structure
```
AI/
├─ AGENTS.md # Rule source of truth (8-section Project Rules & Safety Protocol)
├─ CLAUDE.md # Synced from AGENTS.md, for Claude Code
├─ GEMINI.md # Synced from AGENTS.md, for Gemini CLI
├─ .github/
│ └─ copilot-instructions.md # Synced from AGENTS.md, for GitHub Copilot (@ refs inlined)
├─ README.md # This file (English, default)
├─ README_CN.md # Chinese version
├─ README_JA.md # Japanese version
├─ mcp.example.json # MCP config sample template (placeholder tokens, tool-agnostic)
├─ scripts/
│ └─ sync_rules.py # Sync script (stdlib only)
└─ docs/
├─ INIT-PROMPT.md # New-project init instructions (hand to any AI tool as-is)
├─ prompts/
│ ├─ system-prompt.md # English XML system prompt (with <mcp_policy>, etc.)
│ ├─ architect-subagent.md # Architect sub-role
│ ├─ engineer-subagent.md # Engineer sub-role
│ ├─ critic-subagent.md # Critic sub-role
│ ├─ verifier-subagent.md # Verifier sub-role
│ └─ final-subagent.md # Final sub-role
└─ skills/
├─ registry.md # Tool allowlist + restricted search protocol (11 categories + preferred vendors + inspiration repos)
├─ git-sop.md # Git commit conventions
├─ powershell-tips.md # PowerShell syntax notes on Windows
├─ mcp-registry.md # Manually-connectable MCP list (reference only)
└─ tool-skill-mcp.md # Tool / Skill / MCP relationship and layout
```
> The legacy `.trae/` directory is deprecated. MCP sample config is unified at repo-root `mcp.example.json`, works with every MCP-capable tool, and is no longer bound to Trae.
## How an AI should read this repository
If you are an AI tool wired into this repository (or injected with its rules), read in the following order to fully understand the rules and constraints:
1. **Read `AGENTS.md` first** — the authoritative source of all development iron rules. Its 8 sections cover: workflow & communication, anti-AI-flavor, change scope, anti-deadlock, security & secrets, engineering hygiene, shell & git, skill acquisition, plus Tool / Skill / MCP management.
2. **Then read `docs/prompts/`** — system prompts and sub-role definitions (Architect / Engineer / Critic / Verifier / Final), to understand the division of labor: "plan first, implement later, then review and verify."
3. **Read `docs/skills/` on demand**:
- Check `registry.md` before picking a tool (allowlist + restricted search protocol);
- Check `git-sop.md` before committing;
- Check `powershell-tips.md` on Windows;
- Check `mcp-registry.md` before connecting external systems (**read-only, no auto-config**).
4. **Never** invent rules outside the above files, or download and execute unknown scripts from the web.
The reading order itself is a "guidance chain": README → AGENTS.md → prompts → skills. Any specific task pulls its constraints from this chain; do not start from scratch.
## How to use (bring the rules into your project)
### Method 1: Direct copy (recommended, zero dependencies)
Copy these files to your new project root:
```bash
cp /path/to/AI/AGENTS.md ./AGENTS.md
cp /path/to/AI/CLAUDE.md ./CLAUDE.md
cp /path/to/AI/GEMINI.md ./GEMINI.md
cp -r /path/to/AI/.github ./.github
cp -r /path/to/AI/docs ./docs
```
### Method 2: git submodule (unified updates across projects)
```bash
cd your-new-project
git submodule add https://github.com/MS33834/AI.git .ai-rules
echo '@.ai-rules/AGENTS.md' > AGENTS.md
```
> The remote `https://github.com/MS33834/AI.git` is this rules template repo. If you fork it to your own GitHub account, change it to your repo URL.
### Verify it works
After initializing, ask the agent: "What are the coding standards and the development iron rules I set for this project?"
If it accurately answers "plan before code / stop on ambiguity / no AI flavor / use mature libraries, no hand-rolled low-level code / verify after changes," the rules are injected.
The complete, copy-paste "configuration instructions" are in [docs/INIT-PROMPT.md](docs/INIT-PROMPT.md).
### Multi-device effect
If your tool supports cloud-synced global rules (e.g., Trae's account-wide global rules), configure once on desktop and the same account on mobile applies automatically. Keep `AGENTS.md` and the synced tool files in the project so local project-level rules also take effect.
## How to configure MCP (universal, not bound to any single tool)
MCP (Model Context Protocol) lets AI connect to external systems (GitHub, databases, Notion, filesystem) in a standardized way — more stable and safer than ad-hoc command lines. But it needs long-running processes and permissions, **so the configuration power is in your hands**:
- **AI is forbidden from self-downloading, self-installing, self-starting, or self-configuring MCP** (see `AGENTS.md` §5 red line).
- You pick trusted services from `docs/skills/mcp-registry.md`, and manually paste the corresponding JSON from `mcp.example.json` into each tool's config file (replace placeholders like `${GITHUB_TOKEN}` with your environment variables).
- Config location per tool:
| Tool | Config file path |
|------|--------------|
| Trae | `.trae/mcp.json` |
| Claude Desktop | `claude_desktop_config.json` |
| Cursor | `.cursor/mcp.json` |
| VS Code | `.vscode/mcp.json` (or the `mcp` field in settings.json) |
- Tokens / secrets are always injected via environment variables, never hardcoded into the repo.
## Security & confidentiality red lines (excerpt)
- Absolutely forbid hardcoding API Keys / Tokens / passwords into source code; use `os.getenv()` or `python-dotenv`.
- Never commit `.env` to Git; ensure it is in `.gitignore`.
- When pulling external templates, do not bring in their `.git`, LICENSE, README, or other unrelated files.
- Before committing, run `git status` to check for unexpected files; never auto `git push`, never `git push -f`, never blindly `git add .`.
The full 8-section rules are in [AGENTS.md](AGENTS.md).
## Modifying rules (only touch the source)
Only edit `AGENTS.md`, then run the sync script and the tool-specific files update automatically:
```bash
python scripts/sync_rules.py
```
The script inlines the `@references` in `AGENTS.md` and regenerates `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`.
## Iteration advice
Every time you find the AI repeating the same class of mistake, write the corresponding constraint back into `AGENTS.md` and re-run the sync — the rules get sharper the more you use them. This repository itself obeys these iron rules: every deliverable is planned first, then implemented, then verified.
## Mirror repository (GitCode)
This repository has a public mirror on GitCode, kept in sync with the GitHub source:
- Mirror: https://gitcode.com/badhope/AI
- Source (GitHub): https://github.com/MS33834/AI
Both hold identical content; if the mirror lags, trust the GitHub source.
