English | 简体中文
Opinionated development guides for building software that stays consistent as it grows.
Development guides choose a stack and project layout; UI and documentation guides define organization principles, quality goals, and factual boundaries. They are written for people and AI tools. Requirements should be checkable; illustrative examples can be adapted to the project.
| Guide | Stack | What it fixes |
|---|---|---|
| go-cli-guides.md | cobra · viper · log/slog |
Command tree layout, flag and config precedence, clig.dev conventions for output, exit codes and errors |
| go-server-guides.md | huma v2 · chi · GORM | Layered pkg/ structure, declarative API definitions with generated OpenAPI 3.1, GORM restricted to table mapping and basic CRUD |
| python-server-guides.md | FastAPI · SQLAlchemy Core · Alembic | Layered src/ structure, Pydantic HTTP schemas and generated OpenAPI, SQLAlchemy limited to explicit Core queries without ORM |
| go-tui-guides.md | Bubble Tea · Lip Gloss · Bubbles | The Elm Architecture applied to a real app: model composition, messaging, layout, key bindings — reusing the CLI guide's business layers |
| fe-page-guide-antd.md | Ant Design v5 · ProComponents | How to organize information-dense pages: derive the information model, pick the expression skeleton, order the page, verify the result |
| macos-app-ui-guide.md · 简体中文 | Native · Electron · Stack-independent | Five window compositions, visual defaults, control decision tables, editing and recovery contracts, a worked example, and executable acceptance |
| software-user-manual-guide.md · 简体中文 | Stack-independent | Audience and structure, task-based writing, Chinese prose conventions, visuals, safe validation, and maintenance |
fe-page-guide-antd-demo/ implements all 19 expression skeletons from the frontend guide as working pages — one route per skeleton, with in-memory data and screenshots of every page. Use it to see what each skeleton looks like before choosing one.
cd fe-page-guide-antd-demo
npm install
npm run dev- Follow mainstream community standards and de facto tooling. No bespoke frameworks.
- Go/Python servers follow
handler → service → dal; services may use optional managers for entity business logic. Use one file per entity within each layer. - Prefer
pkg/(importable); useinternal/only when code must not be importable. - Program to interfaces; keep entry points thin —
main.godoes nothing butos.Exit(Execute()). - Use what the chosen stack already provides — huma's built-in validation, stdlib
log/slog, Ant Design's default tokens — instead of adding a parallel layer to do the same job.
Point an AI coding agent at the raw file, or reference it from your project's CLAUDE.md / AGENTS.md:
Follow https://github.com/alswl/guides/blob/master/go-server-guides.md when writing server code.
Important
When a guide conflicts with reality, reality wins. The precedence is: product rules and permission model → the current project's implementation and dependencies → these guides → upstream official docs → historical examples.
Tip
This repository is the single source of truth. If you vendor a guide into another repo, keep the copy read-only and make edits here.
Version v0.0.1-alpha1. The CHANGELOG is generated from Conventional Commits with git-cliff.