Skip to content

docs: add first-principles guidance #207

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
overtrue merged 1 commit into from
Aug 21, 2026
Merged

docs: add first-principles guidance #207

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ Never bypass hooks with `--no-verify`, never disable a failing test instead of f

## Engineering Principles

- **Think from first principles**: do not assume the user fully understands what they want or how to achieve it. Start from the underlying need and problem, stay critical, and stop to discuss when the motivation or goal is unclear. If the goal is clear but the proposed path is not the shortest, say so and recommend a better approach.
- **Code must be as concise and elegant as possible**: the smallest change that solves the problem; reuse existing utilities/components instead of duplicating logic; remove dead code as you go. Single responsibility per function/component; no premature abstraction, clever tricks, or gratuitous indirection — prefer the boring, obvious solution.
- No TODO comments without an issue number.
- Composition over inheritance; explicit data flow over implicit coupling; interfaces over singletons.
Expand Down