Skip to content

README.md

Latest commit

 

History

History
205 lines (159 loc) · 9.55 KB

README.md

File metadata and controls

205 lines (159 loc) · 9.55 KB
Raw

AI-Helpers

A collection of helper (.md / .mdc) files for use across various Gen AI coding tools. The goal is to capture ways of working and reusable instructions so they can be shared and reused without starting from scratch every time.

Supported Tools

Tool Directory Instruction file
Claude Code claude-code/ CLAUDE.md
OpenAI Codex codex/ AGENTS.md
Cursor cursor/ .cursor/rules/*.mdc
OpenCode .opencode/ AGENTS.md

Structure

AI-Helpers/
├── README.md
├── CHANGELOG.md
├── shared/
│   └── AGENTS.md                          ← unified baseline (code style, security, git, etc.)
├── claude-code/
│   ├── README.md
│   └── CLAUDE.md                          ← Claude Code instruction file
├── codex/
│   ├── README.md
│   └── AGENTS.md                          ← Codex instruction file
├── cursor/
│   ├── README.md
│   └── .cursor/
│       └── rules/
│           ├── project-always.mdc         ← always-applied baseline rules
│           ├── typescript.mdc             ← TypeScript-scoped companion rules
│           └── python.mdc                 ← Python-scoped companion rules
├── .opencode/
│   ├── AGENTS.md                          ← OpenCode instruction file
│   ├── README.md
│   ├── skills/                       ← reusable skills (PR descriptions, commits, code review)
│   ├── agents/                        ← custom agents (code-reviewer, review-runner)
│   └── rules/                         ← language-scoped rules (TypeScript, Python)

Native paths

Each tool reads instruction files from specific locations. Understanding the difference between global and project-level paths lets you decide where to install a file.

Claude Code — CLAUDE.md

Scope Path Notes
Global ~/.claude/CLAUDE.md Applies to every Claude Code session on this machine
Project <repo-root>/CLAUDE.md Checked into version control; shared with the team
Local override <repo-root>/CLAUDE.local.md Gitignored; personal preferences not shared with the team

Claude Code also reads supplementary files from .claude/:

Path Purpose
.claude/settings.json Hooks, permissions, model preferences
.claude/commands/<name>.md Custom slash commands (e.g. /commit)
.claude/agents/<name>.md Subagent definitions
.claude/skills/<name>/SKILL.md Reusable skills
.mcp.json or .claude/mcp.json MCP server configuration

Codex — AGENTS.md

Scope Path Notes
Global ~/.codex/AGENTS.md Applies to every Codex session on this machine
Repo root <repo-root>/AGENTS.md Checked into version control; shared with the team
Subdirectory <dir>/AGENTS.md Scoped to tasks within that directory
Override <repo-root>/AGENTS.override.md Gitignored; local overrides merged on top

Cursor — .mdc rule files

Cursor rules live in .cursor/rules/ relative to the project root. Two important requirements:

  1. The file extension must be .mdc — .md or .markdown files are ignored.
  2. Each file must start with a YAML front-matter block:
---
description: Short description shown in Cursor's rule picker
globs:               # optional — restrict rule to matching file patterns (e.g. "**/*.ts")
alwaysApply: true    # true = loads for every Agent interaction; false = semantic match only
---

MCP servers are configured in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) and enabled in Cursor Settings → MCP.

OpenCode — AGENTS.md / AGENTS.local.md

OpenCode reads AGENTS.md from multiple locations with layered precedence:

Scope Path Notes
Project <repo-root>/AGENTS.md Checked into version control; shared with the team
Project <repo-root>/AGENTS.local.md Gitignored; personal overrides
Global ~/.config/opencode/AGENTS.md Applies to every OpenCode session on this machine

OpenCode also supports Claude Code-compatible instruction files: project-level CLAUDE.md (that is, <repo-root>/CLAUDE.md) and global ~/.claude/CLAUDE.md. Skills live in .opencode/skills/<name>/SKILL.md (project) or ~/.config/opencode/skills/<name>/SKILL.md (global).

Quickstart

Copy the file(s) for your tool directly into your project with a single curl command.

Claude Code

# Project-level (add to your repo)
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/claude-code/CLAUDE.md \
  -o CLAUDE.md

# Global (applies to all your projects)
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/claude-code/CLAUDE.md \
  -o ~/.claude/CLAUDE.md

Codex

# Project-level (add to your repo)
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/codex/AGENTS.md \
  -o AGENTS.md

# Global (applies to all your projects)
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/codex/AGENTS.md \
  -o ~/.codex/AGENTS.md

Cursor

mkdir -p .cursor/rules

# Always-applied baseline
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/cursor/.cursor/rules/project-always.mdc \
  -o .cursor/rules/project-always.mdc

# Optional: TypeScript companion rules
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/cursor/.cursor/rules/typescript.mdc \
  -o .cursor/rules/typescript.mdc

# Optional: Python companion rules
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/cursor/.cursor/rules/python.mdc \
  -o .cursor/rules/python.mdc

OpenCode

# Project-level (add to your repo)
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/.opencode/AGENTS.md \
  -o AGENTS.md

# Global (applies to all your projects)
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/.opencode/AGENTS.md \
  -o ~/.config/opencode/AGENTS.md

# Optional: Skills (commit-message, pr-description, codereview)
mkdir -p .opencode/skills
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/.opencode/skills/commit-message/SKILL.md \
  -o .opencode/skills/commit-message/SKILL.md
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/.opencode/skills/pr-description/SKILL.md \
  -o .opencode/skills/pr-description/SKILL.md
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/.opencode/skills/codereview/SKILL.md \
  -o .opencode/skills/codereview/SKILL.md

# Optional: Custom agents (code-reviewer, review-runner)
mkdir -p .opencode/agents
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/.opencode/agents/code-reviewer.md \
  -o .opencode/agents/code-reviewer.md
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/.opencode/agents/review-runner.md \
  -o .opencode/agents/review-runner.md

# Optional: Language-scoped rules (TypeScript, Python)
mkdir -p .opencode/rules
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/.opencode/rules/typescript.md \
  -o .opencode/rules/typescript.md
curl -fsSL https://raw.githubusercontent.com/sunnykgupta/AI-Helpers/main/.opencode/rules/python.md \
  -o .opencode/rules/python.md

Shared baseline

shared/AGENTS.md is the common source of truth for rules that apply regardless of which AI tool you are using (code style, error handling, testing, security, git, workflow, documentation, agentic loops, graph workflows, memory, and human oversight). The tool-specific files extend it with tool-native features and reminders.

Latest agent patterns

The helper files now include a lightweight, vendor-neutral baseline for modern agent systems:

  • Agentic loops — treat agents as Observe → Reason → Act loops with explicit stop criteria, checkpoints, and effort budgets
  • Graph workflows — use directed state graphs, separate planning from execution, and prefer orchestrator-worker topologies
  • Memory & context — distinguish working / episodic / semantic / procedural memory and use write/select/compress/isolate deliberately
  • Human oversight — add approval breakpoints, validate structured outputs before execution, and run high-trust actions in sandboxes

Where these patterns live

File What it adds
shared/AGENTS.md Canonical cross-tool guidance for loops, graphs, memory, and human oversight
claude-code/CLAUDE.md Connects the baseline to Claude Code Plan Mode, hooks, subagents, and context management
codex/AGENTS.md Applies the same baseline to Codex's layered AGENTS.md model and approval-first workflow
cursor/.cursor/rules/project-always.mdc Applies the baseline to always-on Cursor rules alongside MCP and Background Agent notes
.opencode/AGENTS.md Applies the baseline to OpenCode plan/build modes, skills, and custom agents

Contributing

See CHANGELOG.md for a history of changes to the helper files. When updating rules, add an entry there so teams can audit what changed and update their copies.