🛠️ 4. Engineering Principles & Team Agreements
This document combines our core engineering principles and team agreements to guide code quality, design decisions, and collaborative work for the SplitDee project.
💡 Core Principles
1. Users First
Every technical decision, database optimization, or feature implementation must ultimately benefit the end-user. Avoid building features just because they are technically interesting.
2. Documentation is Part of Software
Code without documentation is incomplete. We write, review, and maintain documentation as a first-class citizen of our engineering output.
3. Simple > Clever (KISS Principle)
We prefer simple, readable, and maintainable solutions over complex, clever, or over-engineered implementations. Code is read far more often than it is written.
4. Architecture over Shortcuts
We respect boundaries. Do not break Clean Architecture boundaries or bypass dependency rules for short-term convenience. Shortcuts create technical debt that compounds over time.
5. Automation should Reduce Work
Automate repetitive tasks (testing, deployment, linting, doc generation) to free up engineering capacity for solving complex problems.
6. Every Feature Earns its Place
Avoid feature creep. Every feature must solve a validated user problem and align with the project’s core vision.
🤝 Team Agreements & Preferences
- Readability Over Cleverness: We write clean, readable code with descriptive naming and clear type annotations (e.g., Python type hints).
- Documentation Before Implementation: We define APIs, database schemas, and workflows before we begin writing production code.
- Architecture Before Optimization: Ensure the architecture is correct first. Do not optimize prematurely before identifying actual performance bottlenecks.
- No Hidden Magic: Avoid obscure frameworks, hidden magic behaviors, or undocumented side-effects. Keep the control flow transparent and predictable.
- Document All Important Decisions: Any architectural, database, or API change must be documented instantly in
DECISIONS.mdor the corresponding Obsidian notes.