docs: initialize engineering starter kit
This commit is contained in:
AzuTear
@@ -0,0 +1,247 @@
|
||||
# Decisions
|
||||
|
||||
This document contains Architecture Decision Records (ADRs).
|
||||
|
||||
Use ADRs for decisions that materially affect architecture, operations,
|
||||
security, team workflow, data ownership, public contracts, or long-term
|
||||
maintainability.
|
||||
|
||||
For architecture context, see [ARCHITECTURE.md](ARCHITECTURE.md).
|
||||
For project constraints, see [PROJECT.md](PROJECT.md).
|
||||
|
||||
## Status Values
|
||||
|
||||
- Proposed: under discussion.
|
||||
- Accepted: current decision.
|
||||
- Superseded: replaced by a newer decision.
|
||||
- Deprecated: no longer recommended, but still present.
|
||||
- Rejected: considered and intentionally not chosen.
|
||||
|
||||
## ADR Index
|
||||
|
||||
| ID | Title | Status | Date |
|
||||
| --- | --- | --- | --- |
|
||||
| ADR-000 | ADR template | Accepted | `{{DATE}}` |
|
||||
| ADR-001 | Example: Start with a modular monolith | Example | 2026-06-28 |
|
||||
| ADR-002 | Example: Keep project documentation in the repository | Example | 2026-06-28 |
|
||||
| ADR-003 | Example: Require explicit validation evidence before merge | Example | 2026-06-28 |
|
||||
|
||||
## ADR-000: ADR Template
|
||||
|
||||
### Title
|
||||
|
||||
`{{DECISION_TITLE}}`
|
||||
|
||||
### Status
|
||||
|
||||
`{{STATUS}}`
|
||||
|
||||
### Date
|
||||
|
||||
`{{DATE}}`
|
||||
|
||||
### Context
|
||||
|
||||
`{{CONTEXT}}`
|
||||
|
||||
Describe the environment, constraints, project stage, team needs, and forces
|
||||
that make the decision necessary.
|
||||
|
||||
### Problem
|
||||
|
||||
`{{PROBLEM}}`
|
||||
|
||||
State the specific problem being solved. Avoid combining unrelated decisions.
|
||||
|
||||
### Alternatives
|
||||
|
||||
| Alternative | Summary |
|
||||
| --- | --- |
|
||||
| `{{ALTERNATIVE_1}}` | `{{ALTERNATIVE_1_SUMMARY}}` |
|
||||
| `{{ALTERNATIVE_2}}` | `{{ALTERNATIVE_2_SUMMARY}}` |
|
||||
| `{{ALTERNATIVE_3}}` | `{{ALTERNATIVE_3_SUMMARY}}` |
|
||||
|
||||
### Pros
|
||||
|
||||
- `{{PRO}}`
|
||||
|
||||
### Cons
|
||||
|
||||
- `{{CON}}`
|
||||
|
||||
### Decision
|
||||
|
||||
`{{DECISION}}`
|
||||
|
||||
Write the chosen option and why it best fits the current constraints.
|
||||
|
||||
### Consequences
|
||||
|
||||
- `{{CONSEQUENCE}}`
|
||||
|
||||
Document expected benefits, costs, operational impacts, migration needs, and
|
||||
future review triggers.
|
||||
|
||||
## ADR-001: Example: Start With A Modular Monolith
|
||||
|
||||
### Title
|
||||
|
||||
Start with a modular monolith before introducing microservices.
|
||||
|
||||
### Status
|
||||
|
||||
Example
|
||||
|
||||
### Date
|
||||
|
||||
2026-06-28
|
||||
|
||||
### Context
|
||||
|
||||
The fictional project `Atlas Desk` is a new workflow application with one small
|
||||
team, one primary database, and requirements that are still evolving.
|
||||
|
||||
### Problem
|
||||
|
||||
The team needs clear module boundaries without accepting the operational cost of
|
||||
distributed services too early.
|
||||
|
||||
### Alternatives
|
||||
|
||||
| Alternative | Summary |
|
||||
| --- | --- |
|
||||
| Layered monolith | Simple to build, but feature boundaries may become unclear. |
|
||||
| Modular monolith | Strong internal boundaries with one deployable unit. |
|
||||
| Microservices | Independent deployments, but higher operational and data consistency cost. |
|
||||
|
||||
### Pros
|
||||
|
||||
- Preserves deployment simplicity.
|
||||
- Supports clear module ownership.
|
||||
- Avoids premature distributed transactions and network failure modes.
|
||||
- Allows extraction of services later when boundaries are proven.
|
||||
|
||||
### Cons
|
||||
|
||||
- Requires discipline to maintain module boundaries.
|
||||
- Independent scaling by module is limited.
|
||||
- Poor internal boundaries can still create a tightly coupled system.
|
||||
|
||||
### Decision
|
||||
|
||||
Use a modular monolith as the initial architecture.
|
||||
|
||||
### Consequences
|
||||
|
||||
- Module boundaries must be documented in [ARCHITECTURE.md](ARCHITECTURE.md).
|
||||
- Cross-module access must go through public interfaces.
|
||||
- Service extraction can be reconsidered when team scale, traffic, or ownership
|
||||
pressure justifies it.
|
||||
|
||||
## ADR-002: Example: Keep Project Documentation In The Repository
|
||||
|
||||
### Title
|
||||
|
||||
Keep durable engineering documentation in the source repository.
|
||||
|
||||
### Status
|
||||
|
||||
Example
|
||||
|
||||
### Date
|
||||
|
||||
2026-06-28
|
||||
|
||||
### Context
|
||||
|
||||
The project will use issue trackers and chat for coordination, but architecture,
|
||||
setup, and operating knowledge must remain discoverable by humans and AI agents.
|
||||
|
||||
### Problem
|
||||
|
||||
External documentation often drifts from code and is harder for development
|
||||
tools to discover during implementation.
|
||||
|
||||
### Alternatives
|
||||
|
||||
| Alternative | Summary |
|
||||
| --- | --- |
|
||||
| Repository documentation | Versioned with code and easy for agents to read. |
|
||||
| Wiki | Easier non-developer editing, but often drifts from code changes. |
|
||||
| Chat-only knowledge | Fast, but not durable or discoverable. |
|
||||
|
||||
### Pros
|
||||
|
||||
- Documentation changes can be reviewed with code.
|
||||
- Agents and developers can discover project context locally.
|
||||
- Historical context remains connected to commits.
|
||||
|
||||
### Cons
|
||||
|
||||
- Non-developers may find editing less convenient.
|
||||
- Documentation quality still requires review discipline.
|
||||
- Large diagrams or rich media may need external tooling.
|
||||
|
||||
### Decision
|
||||
|
||||
Keep durable engineering documentation in the repository under `docs/`.
|
||||
|
||||
### Consequences
|
||||
|
||||
- Pull requests that change architecture or operations should update docs.
|
||||
- Temporary planning can live elsewhere, but accepted decisions belong here.
|
||||
- Links must be reviewed as part of documentation changes.
|
||||
|
||||
## ADR-003: Example: Require Explicit Validation Evidence Before Merge
|
||||
|
||||
### Title
|
||||
|
||||
Require explicit validation evidence before merging changes.
|
||||
|
||||
### Status
|
||||
|
||||
Example
|
||||
|
||||
### Date
|
||||
|
||||
2026-06-28
|
||||
|
||||
### Context
|
||||
|
||||
The project may use AI-assisted development and multiple contributors. Reviewers
|
||||
need a reliable way to understand how changes were checked.
|
||||
|
||||
### Problem
|
||||
|
||||
Pull requests without validation evidence increase review time and regression
|
||||
risk.
|
||||
|
||||
### Alternatives
|
||||
|
||||
| Alternative | Summary |
|
||||
| --- | --- |
|
||||
| No required evidence | Fastest locally, but makes review less reliable. |
|
||||
| Validation summary in PR | Lightweight and visible to reviewers. |
|
||||
| Full test report artifact only | Detailed, but harder to scan for small changes. |
|
||||
|
||||
### Pros
|
||||
|
||||
- Reviewers can evaluate risk quickly.
|
||||
- Missing tests or blocked checks are visible.
|
||||
- AI-generated changes become easier to trust or challenge.
|
||||
|
||||
### Cons
|
||||
|
||||
- Contributors must spend time recording checks.
|
||||
- Some exploratory changes may need a lighter process before formal review.
|
||||
|
||||
### Decision
|
||||
|
||||
Every pull request must include a short validation section listing commands,
|
||||
manual checks, or reasons validation could not be run.
|
||||
|
||||
### Consequences
|
||||
|
||||
- PR templates should include validation.
|
||||
- Reviewers can block merges when risk is high and evidence is missing.
|
||||
- Failed or skipped validation must be explained.
|
||||
Reference in New Issue
Block a user