|
1 | | -# Engineering Principles (Routing Index) |
| 1 | +# Engineering Principles (Agent-Relevant Subset) |
2 | 2 |
|
3 | | -> **Source:** Alexander's battle-tested wisdom from years of software engineering. Full details in `docs/ENGINEERING-PRINCIPLES.md`. |
| 3 | +> 10 of Alexander's 26 principles that directly influence AI agent behavior. |
| 4 | +> Full list with examples: `docs/ENGINEERING-PRINCIPLES.md` |
4 | 5 |
|
5 | | -## Problem Solving & Design |
6 | | - |
7 | | -**IF starting new feature** → Remember: You're paid to solve problems, not write code (#1) |
8 | | -- Understand business problem first |
9 | | -- Consider non-code solutions |
10 | | -- Work backward from desired outcome |
| 6 | +**IF starting new feature** → You're paid to solve problems, not write code (#1) |
| 7 | +Understand the business problem. Consider non-code solutions. Work backward from desired outcome. |
11 | 8 |
|
12 | 9 | **IF evaluating approaches** → No "best" solution, only trade-offs (#2) |
13 | | -- Document decision context |
14 | | -- Know what you're optimizing for |
15 | | -- If stuck in circles → need more constraints |
| 10 | +Document decision context. Know what you're optimizing for. |
16 | 11 |
|
17 | 12 | **IF adding code** → Less code is better code (#3) |
18 | | -- Justify every line's existence |
19 | | -- Remove unused code immediately |
20 | | -- Solve actual problems, not future maybes |
21 | | - |
22 | | -**IF adding dependency** → Every dependency is a liability (#4) |
23 | | -- Audit regularly, remove unused |
24 | | -- Check maintenance health |
25 | | -- Evaluate total cost of ownership |
26 | | - |
27 | | -**IF designing system** → Design for change (#6) |
28 | | -- Software is never finished |
29 | | -- Make it easy to modify |
30 | | -- Refactor incrementally, not "big rewrite" |
31 | | - |
32 | | -## Shipping & Iteration |
33 | | - |
34 | | -**IF building feature** → Ship early, iterate often (#5) |
35 | | -- Perfect is the enemy of done |
36 | | -- Get real user feedback fast |
37 | | -- Validate before heavy investment |
38 | | - |
39 | | -**IF writing code** → Write for humans first, computers second (#7) |
40 | | -- Code is read 100x more than written |
41 | | -- Clarity over cleverness |
42 | | -- Think about the 3 AM debugger |
| 13 | +Justify every line. Remove unused code immediately. Solve actual problems, not future maybes. |
43 | 14 |
|
44 | 15 | **IF adding abstraction** → Complexity kills projects (#8) |
45 | | -- KISS: Keep It Simple, Stupid |
46 | | -- Prefer boring, straightforward solutions |
47 | | -- Abstraction should hide complexity, not create it |
48 | | - |
49 | | -## Debugging & Root Causes |
| 16 | +KISS. Prefer boring, straightforward solutions. Abstraction should hide complexity, not create it. |
50 | 17 |
|
51 | 18 | **IF encountering bug** → Fix root causes, not symptoms (#9) |
52 | | -- Resist quick patches |
53 | | -- Understand why it happened |
54 | | -- Fix the class of bugs, not one instance |
| 19 | +Resist quick patches. Understand why it happened. Fix the class of bugs, not one instance. |
55 | 20 |
|
56 | 21 | **IF something unexpected** → Understand the "why" before moving on (#10) |
57 | | -- Don't trial-and-error until it works |
58 | | -- What assumption was wrong? |
59 | | -- Hope is not a strategy |
60 | | - |
61 | | -**IF debugging/optimizing** → Change one thing at a time (#24) |
62 | | -- Can't know what worked if you change multiple things |
63 | | -- Measure → change → measure again |
64 | | -- Scientific method applies to software |
65 | | - |
66 | | -## Code Quality & Collaboration |
67 | | - |
68 | | -**IF reviewing code** → Don't fall in love with your code (#11) |
69 | | -- Code is a tool, not your baby |
70 | | -- Be willing to delete and refactor |
71 | | -- Remove ego from technical decisions |
72 | | - |
73 | | -**IF seeing "bad" code** → Seek to understand before judging (#12) |
74 | | -- What constraints did they face? |
75 | | -- What was the context? |
76 | | -- Review code with empathy |
| 22 | +Don't trial-and-error until it works. What assumption was wrong? |
77 | 23 |
|
78 | 24 | **IF making decisions** → Document the "why" (#13) |
79 | | -- ADRs, RFCs, comments, design docs |
80 | | -- Explain context and alternatives |
81 | | -- Save future-you hours of confusion |
82 | | - |
83 | | -**IF committing** → Write meaningful commit messages (#14) |
84 | | -- Tell the story: what, where, why |
85 | | -- "Fix bug" tells nothing |
86 | | -- Clear communication = senior behavior |
87 | | - |
88 | | -## Automation & Process |
89 | | - |
90 | | -**IF debating style** → Automate everything that can be automated (#15) |
91 | | -- Formatters and linters end debates |
92 | | -- CI/CD isn't optional |
93 | | -- Build safeguards into pipelines |
94 | | - |
95 | | -**IF submitting PR** → Code reviews improve more than quality (#16) |
96 | | -- Share knowledge across team |
97 | | -- Keep PRs small and focused |
98 | | -- Build people, not just software |
99 | | - |
100 | | -**IF learning** → Never stop learning and questioning (#17) |
101 | | -- Chase understanding, not new tech |
102 | | -- Learn fundamentals + adjacent skills |
103 | | -- Run toward the fire; that's where you grow |
104 | | - |
105 | | -**IF stuck** → Ask for help when stuck (#18) |
106 | | -- Show what you've tried |
107 | | -- Provide context |
108 | | -- Asking good questions is a strength |
109 | | - |
110 | | -## Estimates & Communication |
111 | | - |
112 | | -**IF estimating** → Estimations are never true (#19) |
113 | | -- Communicate as ranges with confidence |
114 | | -- Include uncertainty |
115 | | -- Update early when estimates are off |
116 | | - |
117 | | -## Production & Operations |
118 | | - |
119 | | -**IF deploying** → You can't operate what you can't observe (#20) |
120 | | -- Log precisely, not excessively |
121 | | -- Instrument key metrics from the start |
122 | | -- Reliability matters more than features |
123 | | - |
124 | | -**IF handling input** → Never trust user input (#21) |
125 | | -- Every input is potential attack vector |
126 | | -- Validate at the boundary |
127 | | -- Use parameterized queries, not strings |
| 25 | +ADRs, RFCs, design docs. Explain context and alternatives. |
128 | 26 |
|
129 | 27 | **IF error occurs** → Errors should fail loudly and immediately (#22) |
130 | | -- Silent failures = debugging nightmares |
131 | | -- Don't swallow exceptions |
132 | | -- Provide clear context about what failed |
| 28 | +Silent failures = debugging nightmares. Provide clear context about what failed. |
133 | 29 |
|
134 | | -**IF optimizing** → Measure first, optimize second (#23) |
135 | | -- Profile to find actual bottlenecks |
136 | | -- Don't sacrifice clarity for micro-optimizations |
137 | | -- Know what you're optimizing for |
138 | | - |
139 | | -## API Design & Architecture |
| 30 | +**IF debugging/optimizing** → Change one thing at a time (#24) |
| 31 | +Can't know what worked if you change multiple things. Measure → change → measure again. |
140 | 32 |
|
141 | 33 | **IF designing API** → Easy to use correctly, hard to misuse (#25) |
142 | | -- Use types to enforce constraints |
143 | | -- Make invalid states unrepresentable |
144 | | -- Good defaults + clear errors |
145 | | - |
146 | | -**IF choosing patterns** → Favor composition over inheritance (#25b) |
147 | | -- More flexible, less coupling |
148 | | -- Each module = clear, focused purpose |
149 | | -- Maximize cohesion, minimize coupling |
150 | | - |
151 | | -## Team & Culture |
152 | | - |
153 | | -**IF working with others** → Be a good human (#26) |
154 | | -- Technical brilliance < collaboration skills |
155 | | -- Be kind, patient, share credit |
156 | | -- Build psychological safety |
157 | | -- Focus on fixing problems, not assigning blame |
158 | | - |
159 | | ---- |
160 | | - |
161 | | -**For full details with examples:** Read `docs/ENGINEERING-PRINCIPLES.md` |
| 34 | +Use types to enforce constraints. Make invalid states unrepresentable. Good defaults + clear errors. |
0 commit comments