Engineering reference · 33 guides
AI Coding Guidelines
Engineering standards for AI coding agents and the people who review their work — covering toolchains, day-to-day practices, library stacks, and platform patterns, organized for fast task-based reading.
Use in your project
Run this in your project directory, then ask your agent to apply these guidelines to your task.
pnpm dlx skills add fang2hou/ai-coding-guidelines@apply-guidelinesYou can also paste these instructions into your AI coding agent without installing the skill.
Apply the guidelines from https://github.com/fang2hou/ai-coding-guidelines for this task.
Start at PORTAL.md and follow its reading recipes.Start here
Read these two documents before any task.
Reading paths by task
Pick your task and read the linked guidelines in order.
TypeScript / frontend project
TypeScript backend service
Python API service
UI styling & components
iOS 27 / macOS 27 Liquid Glass app
Testing, Git & CI/CD
Browse by category
Every guideline, grouped by the part of the stack it governs.
Principles
1 guideCore maxims behind every rule: fast validation, fewer choices, fixing root causes.
Practices
12 guidesDay-to-day engineering: code style, testing, documentation, dependencies, CI, and security.
- Agent Operating ProtocolBefore making a non-trivial change, an AI agent should:
- Authoring AGENTS.mdAGENTS.md is the entry point for AI agents in a repository. Agent tools load it at the start of every session and limit…
- Architecture GovernanceRecord architectural boundaries and invariants in ARCHITECTURE.md so AI agents do not break them by accident.
- Change DisciplineApply this checklist to every non-trivial change before handing it over for review, in addition to the operating protoc…
- Coding StandardsFollow the standard conventions of the language and framework you are using; do not invent custom variants.
- Corner RadiusCorner radius is a system, not a per-element value: define a small token scale once per project and take every radius f…
- Dependency DisciplineBefore adding a dependency, answer these five questions in order:
- Language PolicyChoose each of the following languages independently; never infer one from another:
- PipelineThese rules apply to CI/CD pipelines in any system — GitHub Actions, GitLab CI, CircleCI, Jenkins, or any other. Tool-s…
- Required Project DocumentationEvery project must maintain AGENTS.md, README.md, DEVELOPMENT.md, and CONTRIBUTING.md. ARCHITECTURE.md becomes required…
- SecurityNever commit secrets or sensitive data to the repository, including:
- Testing StrategyWrite tests to verify real behavior, not to pad coverage numbers.
Toolchain
9 guidesStandard tools per language ecosystem — identical on your machine and in CI.
- DatabricksDatabricks is the preferred platform for data and AI workloads: use Databricks Apps to host applications, and Databrick…
- Git WorkflowAll project commits must follow the Conventional Commits specification.
- GitHub ActionsGitHub Actions is the standard CI/CD platform and the default choice when the user has not specified a pipeline system.…
- Go ToolchainTypeScript and Python are the default languages for AI-assisted development. Go is not a default choice — use it only w…
- misemise is mandatory for every project.
- Python ToolchainPython and TypeScript are the default languages for AI-assisted development because they have the strongest library and…
- Quality GatesUse prek as the standard pre-commit framework.
- Rust ToolchainTypeScript and Python are the default languages for AI-assisted development. Rust is not a default choice — use it only…
- TypeScript ToolchainTypeScript and Python are the default languages for AI-assisted development because they have the strongest library and…
Libraries
8 guidesDefault frameworks and libraries for web frontends, HTTP APIs, and AI features.
- AgentationSituational — enable Agentation during frontend iteration and testing to turn visual feedback into structured context f…
- Frontend Framework: Vite vs Next.jsPreferred — Vite is the default frontend framework; choose Next.js only when the project genuinely needs full-stack Rea…
- Go API StackPreferred — Use Echo as the Go web framework, with github.com/go-playground/validator/v10 for request validation. This…
- Python API StackPreferred — FastAPI + Pydantic + Uvicorn is the standard Python API stack; adopt all three together, not as separate pi…
- Svelte (Svelte 5 + SvelteKit)Situational — Svelte 5 with SvelteKit is approved for small personal and experimental projects where developer enjoymen…
- Tailwind CSSSituational — Tailwind CSS is used when the project already runs Tailwind or its component kit requires it. Native CSS…
- TypeScript BackendPreferred — Use Hono for TypeScript backend services. The default runtime is Node.js on the Active LTS line; Web-standa…
- Vercel AI SDKSituational — use the Vercel AI SDK only when a Next.js project directly uses its streaming or UI integration features.
Platforms
3 guidesDesign and implementation rules for iOS 27 and macOS 27 Liquid Glass.
- Liquid Glass API referenceReference for iOS 27 and native macOS 27 apps built with Xcode 27, with deployment targets set to 27.0. Verified on 202…
- Liquid Glass design (Apple platforms)For new iOS 27 and native macOS 27 apps, adopt Liquid Glass through system navigation and controls first. Add custom gl…
- Liquid Glass implementation patternsUse these recipes for iOS 27 and native macOS 27 apps built with Xcode 27. Set the matching deployment target to 27.0.…