APoSD Code Review Skill

English | 简体中文

A reusable code-review skill distilled from John Ousterhout's A Philosophy of Software Design. It works across multiple AI coding assistants and ships in both English and Chinese.

The single thing it optimizes for is reducing complexity. It gives an assistant a concrete vocabulary and checklist — deep modules, information hiding, interface-over-implementation, pulling complexity downwards, defining errors out of existence, and a red-flags list — to judge whether a change makes a system simpler or more complex to understand and modify.

From the book: "The most important technique for achieving simplicity is to design modules so that they are deep."

Core principles

Principle	Addresses
Deep modules	Simple interface hiding powerful functionality; avoid shallow modules
Information hiding	Encapsulate decisions; stop information leakage across modules
Interface over implementation	Simple, consistent, obvious interfaces that say what, not how
Pull complexity downwards	The module absorbs complexity so callers stay simple
Define errors out of existence	Fewer exceptions and special cases; unify the model
Comments capture the why	Precision or higher-level intuition, never a restatement of code

What's in this repo

.
├── skills/code-review-aposd/
│   ├── SKILL.md          # Full skill (English)
│   └── SKILL.zh.md       # Full skill (Chinese)
├── .claude-plugin/       # Claude Code plugin + marketplace manifests
├── .cursor/rules/        # Cursor project rule
├── CLAUDE.md             # Condensed guidelines for Claude Code
├── AGENTS.md             # Condensed guidelines for Copilot / Codex / AGENTS.md-aware tools
├── README.md            # This file
└── README.zh.md         # Chinese README

Usage

Claude Code — plugin (recommended)

/plugin marketplace add ethanyhou/aposd-code-review-skill
/plugin install aposd-code-review-skill@aposd-skills

This installs the skill so it's available across your projects.

Claude Code — CLAUDE.md (per-project)

New project:

curl -o CLAUDE.md https://raw.githubusercontent.com/ethanyhou/aposd-code-review-skill/main/CLAUDE.md

Existing project (append):

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/ethanyhou/aposd-code-review-skill/main/CLAUDE.md >> CLAUDE.md

Cursor

Copy .cursor/rules/code-review-aposd.mdc into your project's .cursor/rules/ directory, or open this repo in Cursor directly.

GitHub Copilot — skill (recommended)

Copilot CLI and Copilot in the IDE discover skills under .github/skills/. Copy the skill folder into your project so you can invoke it on demand (e.g. "review this diff with the code-review-aposd skill"):

mkdir -p .github/skills
curl -fsSL https://raw.githubusercontent.com/ethanyhou/aposd-code-review-skill/main/skills/code-review-aposd/SKILL.md \
  -o .github/skills/code-review-aposd/SKILL.md

Prefer Chinese? Use SKILL.zh.md from the same path.

GitHub Copilot, Codex, and other AGENTS.md-aware assistants

For always-on guidance (no explicit invocation), copy AGENTS.md to your project root, or merge it into an existing one. Assistants that read AGENTS.md pick up the guidelines automatically. Use this when you want the principles applied to every change; use the skill above when you want to trigger a focused review on demand.

As a plain rubric

Read skills/code-review-aposd/SKILL.md (or the Chinese version) and walk the red-flags checklist against any diff.

Attribution

The ideas summarized here are from A Philosophy of Software Design by John Ousterhout. This repository is an original distillation for code review and does not reproduce the book's text.

License

MIT