docs: initialize engineering starter kit
This commit is contained in:
AzuTear
@@ -0,0 +1,193 @@
|
||||
# Architecture
|
||||
|
||||
This document describes the structure, boundaries, flows, and technical rules of
|
||||
the system.
|
||||
|
||||
For project intent and runtime facts, see [PROJECT.md](PROJECT.md).
|
||||
For coding standards, see [CONVENTIONS.md](CONVENTIONS.md).
|
||||
For recorded trade-offs, see [DECISIONS.md](DECISIONS.md).
|
||||
|
||||
## High-Level Overview
|
||||
|
||||
`{{PROJECT_NAME}}` uses `{{ARCHITECTURE_STYLE}}` to support
|
||||
`{{PRIMARY_USE_CASES}}`.
|
||||
|
||||
Replace this section with a concise explanation of the system's major parts,
|
||||
their responsibilities, and the constraints that shaped the architecture.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
User["User or External Client"]
|
||||
Interface["Interface Layer<br/>API, UI, CLI, Worker"]
|
||||
Application["Application Layer<br/>Use cases and orchestration"]
|
||||
Domain["Domain Layer<br/>Rules and invariants"]
|
||||
Infrastructure["Infrastructure Layer<br/>Database, queues, files, services"]
|
||||
External["External Systems"]
|
||||
|
||||
User --> Interface
|
||||
Interface --> Application
|
||||
Application --> Domain
|
||||
Application --> Infrastructure
|
||||
Infrastructure --> External
|
||||
```
|
||||
|
||||
## Architecture Style
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Style | `{{ARCHITECTURE_STYLE}}` |
|
||||
| Primary reason | `{{ARCHITECTURE_REASON}}` |
|
||||
| Main trade-off | `{{ARCHITECTURE_TRADE_OFF}}` |
|
||||
| Related decision | [DECISIONS.md](DECISIONS.md) |
|
||||
|
||||
Common examples include layered architecture, modular monolith, microservices,
|
||||
event-driven architecture, hexagonal architecture, desktop MVC/MVVM, or
|
||||
game-specific entity/component systems.
|
||||
|
||||
## Folder Structure
|
||||
|
||||
```text
|
||||
{{PROJECT_ROOT}}/
|
||||
{{SOURCE_FOLDER}}/
|
||||
{{TEST_FOLDER}}/
|
||||
{{DOCS_FOLDER}}/
|
||||
{{BUILD_FOLDER}}/
|
||||
```
|
||||
|
||||
| Folder | Responsibility |
|
||||
| --- | --- |
|
||||
| `{{FOLDER}}` | `{{FOLDER_RESPONSIBILITY}}` |
|
||||
|
||||
Keep generated files, build outputs, and framework artifacts out of source
|
||||
folders unless the framework requires them.
|
||||
|
||||
## Module Responsibilities
|
||||
|
||||
| Module | Responsibility | Owned Data | Public Interface |
|
||||
| --- | --- | --- | --- |
|
||||
| `{{MODULE_NAME}}` | `{{MODULE_RESPONSIBILITY}}` | `{{OWNED_DATA}}` | `{{PUBLIC_INTERFACE}}` |
|
||||
|
||||
Modules should have clear ownership. Shared utilities should remain small and
|
||||
generic; domain behavior belongs with the module that owns the domain concept.
|
||||
|
||||
## Dependency Rules
|
||||
|
||||
Define allowed dependencies explicitly.
|
||||
|
||||
- `{{DEPENDENCY_RULE_1}}`
|
||||
- `{{DEPENDENCY_RULE_2}}`
|
||||
- `{{DEPENDENCY_RULE_3}}`
|
||||
|
||||
Recommended default:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
UI["UI, API, CLI, Worker"]
|
||||
App["Application"]
|
||||
Domain["Domain"]
|
||||
Infra["Infrastructure"]
|
||||
|
||||
UI --> App
|
||||
App --> Domain
|
||||
App --> Infra
|
||||
Infra --> Domain
|
||||
```
|
||||
|
||||
Domain code should not depend on delivery mechanisms, databases, network
|
||||
clients, or framework-specific runtime concerns unless the project intentionally
|
||||
uses an architecture where that trade-off is accepted and recorded.
|
||||
|
||||
## Request Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant Interface
|
||||
participant Application
|
||||
participant Domain
|
||||
participant Infrastructure
|
||||
|
||||
Client->>Interface: Request or command
|
||||
Interface->>Application: Validate transport shape
|
||||
Application->>Domain: Execute business rule
|
||||
Application->>Infrastructure: Persist or integrate
|
||||
Infrastructure-->>Application: Result
|
||||
Application-->>Interface: Response model
|
||||
Interface-->>Client: Response
|
||||
```
|
||||
|
||||
Document deviations for async jobs, desktop workflows, games, or event-driven
|
||||
flows.
|
||||
|
||||
## Data Flow
|
||||
|
||||
| Data | Source | Owner | Storage | Consumers |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `{{DATA_ENTITY}}` | `{{DATA_SOURCE}}` | `{{DATA_OWNER}}` | `{{DATA_STORAGE}}` | `{{DATA_CONSUMERS}}` |
|
||||
|
||||
Data ownership should be clear before adding shared tables, shared schemas,
|
||||
cross-service writes, or replicated state.
|
||||
|
||||
## Domain Model
|
||||
|
||||
| Concept | Meaning | Invariants |
|
||||
| --- | --- | --- |
|
||||
| `{{DOMAIN_CONCEPT}}` | `{{DOMAIN_MEANING}}` | `{{DOMAIN_INVARIANTS}}` |
|
||||
|
||||
Use this section for durable business concepts, not framework models or DTOs.
|
||||
|
||||
## Integration Points
|
||||
|
||||
| Integration | Direction | Protocol | Reliability Expectations |
|
||||
| --- | --- | --- | --- |
|
||||
| `{{INTEGRATION_NAME}}` | `{{INBOUND_OR_OUTBOUND}}` | `{{PROTOCOL}}` | `{{RELIABILITY_EXPECTATIONS}}` |
|
||||
|
||||
For each integration, document authentication, retry behavior, timeouts,
|
||||
idempotency, and failure handling.
|
||||
|
||||
## Security
|
||||
|
||||
| Area | Policy |
|
||||
| --- | --- |
|
||||
| Authentication | `{{AUTHENTICATION_POLICY}}` |
|
||||
| Authorization | `{{AUTHORIZATION_POLICY}}` |
|
||||
| Secrets | `{{SECRETS_POLICY}}` |
|
||||
| Input validation | `{{INPUT_VALIDATION_POLICY}}` |
|
||||
| Output encoding | `{{OUTPUT_ENCODING_POLICY}}` |
|
||||
| Audit logging | `{{AUDIT_LOGGING_POLICY}}` |
|
||||
| Dependency security | `{{DEPENDENCY_SECURITY_POLICY}}` |
|
||||
|
||||
Security-sensitive decisions should be recorded in [DECISIONS.md](DECISIONS.md).
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error Type | Handling Policy | User/Client Response |
|
||||
| --- | --- | --- |
|
||||
| Validation error | `{{VALIDATION_ERROR_POLICY}}` | `{{VALIDATION_RESPONSE}}` |
|
||||
| Domain error | `{{DOMAIN_ERROR_POLICY}}` | `{{DOMAIN_RESPONSE}}` |
|
||||
| Infrastructure error | `{{INFRASTRUCTURE_ERROR_POLICY}}` | `{{INFRASTRUCTURE_RESPONSE}}` |
|
||||
| Unexpected error | `{{UNEXPECTED_ERROR_POLICY}}` | `{{UNEXPECTED_RESPONSE}}` |
|
||||
|
||||
Errors should preserve enough diagnostic context for operators without exposing
|
||||
secrets or internal implementation details to users.
|
||||
|
||||
## Performance
|
||||
|
||||
| Concern | Expectation | Measurement |
|
||||
| --- | --- | --- |
|
||||
| Latency | `{{LATENCY_EXPECTATION}}` | `{{LATENCY_MEASUREMENT}}` |
|
||||
| Throughput | `{{THROUGHPUT_EXPECTATION}}` | `{{THROUGHPUT_MEASUREMENT}}` |
|
||||
| Resource usage | `{{RESOURCE_EXPECTATION}}` | `{{RESOURCE_MEASUREMENT}}` |
|
||||
|
||||
Document known hot paths and the expected performance test strategy.
|
||||
|
||||
## Scalability
|
||||
|
||||
| Dimension | Current Strategy | Future Strategy |
|
||||
| --- | --- | --- |
|
||||
| Traffic | `{{TRAFFIC_STRATEGY}}` | `{{TRAFFIC_FUTURE_STRATEGY}}` |
|
||||
| Data volume | `{{DATA_VOLUME_STRATEGY}}` | `{{DATA_VOLUME_FUTURE_STRATEGY}}` |
|
||||
| Team size | `{{TEAM_SCALE_STRATEGY}}` | `{{TEAM_SCALE_FUTURE_STRATEGY}}` |
|
||||
|
||||
Scalability work should be driven by measured pressure or clear product
|
||||
requirements, not premature complexity.
|
||||
@@ -0,0 +1,107 @@
|
||||
# Checklists
|
||||
|
||||
Use these concise checklists as quality gates. Expand them only when repeated
|
||||
project experience proves that more detail is necessary.
|
||||
|
||||
For workflow details, see [workflow.md](workflow.md).
|
||||
For code standards, see [CONVENTIONS.md](CONVENTIONS.md).
|
||||
For releases, see [release-process.md](release-process.md).
|
||||
|
||||
## Feature Development
|
||||
|
||||
- [ ] Objective and acceptance criteria are clear.
|
||||
- [ ] Relevant docs and existing implementation were read.
|
||||
- [ ] Architecture boundaries are respected.
|
||||
- [ ] User-facing behavior is implemented.
|
||||
- [ ] Edge cases and failure states are handled.
|
||||
- [ ] Tests or manual checks cover the main behavior.
|
||||
- [ ] Documentation is updated when behavior or setup changed.
|
||||
|
||||
## Bug Fix
|
||||
|
||||
- [ ] Observed behavior is understood.
|
||||
- [ ] Expected behavior is confirmed.
|
||||
- [ ] Root cause is identified before changing code.
|
||||
- [ ] Fix is scoped to the cause.
|
||||
- [ ] Regression coverage is added when practical.
|
||||
- [ ] Validation proves the bug is fixed.
|
||||
- [ ] Remaining risk is documented.
|
||||
|
||||
## Refactoring
|
||||
|
||||
- [ ] Behavior-preserving intent is explicit.
|
||||
- [ ] Existing tests or checks are identified.
|
||||
- [ ] Changes are small and reviewable.
|
||||
- [ ] Public contracts remain stable or the break is approved.
|
||||
- [ ] Dead code is removed only when safe.
|
||||
- [ ] Validation is run before and after meaningful changes.
|
||||
|
||||
## API Review
|
||||
|
||||
- [ ] Consumer needs are clear.
|
||||
- [ ] Request and response contracts are stable.
|
||||
- [ ] Validation errors are consistent.
|
||||
- [ ] Authorization is explicit.
|
||||
- [ ] Pagination, filtering, and sorting are defined where needed.
|
||||
- [ ] Idempotency is addressed for retryable writes.
|
||||
- [ ] Versioning and compatibility are considered.
|
||||
|
||||
## Database Review
|
||||
|
||||
- [ ] Data ownership is clear.
|
||||
- [ ] Constraints protect important invariants.
|
||||
- [ ] Indexes match expected query patterns.
|
||||
- [ ] Migration is reversible or rollback-safe.
|
||||
- [ ] Backfill and deployment order are documented.
|
||||
- [ ] Retention and privacy requirements are addressed.
|
||||
- [ ] Backup and restore impact is understood.
|
||||
|
||||
## Security Review
|
||||
|
||||
- [ ] Authentication is required where expected.
|
||||
- [ ] Authorization is enforced server-side or at the trusted boundary.
|
||||
- [ ] Inputs are validated.
|
||||
- [ ] Outputs are safely encoded or serialized.
|
||||
- [ ] Secrets are not logged or committed.
|
||||
- [ ] Sensitive data exposure is minimized.
|
||||
- [ ] Dependency risk is reviewed.
|
||||
- [ ] Abuse cases and rate limits are considered where relevant.
|
||||
|
||||
## Performance Review
|
||||
|
||||
- [ ] Hot paths are identified.
|
||||
- [ ] Database queries are bounded and indexed.
|
||||
- [ ] Network calls have timeouts and retry policy where appropriate.
|
||||
- [ ] Expensive work is cached, batched, async, or justified.
|
||||
- [ ] UI updates avoid unnecessary re-rendering where relevant.
|
||||
- [ ] Performance expectations are measurable.
|
||||
|
||||
## Pull Request
|
||||
|
||||
- [ ] Summary explains what and why.
|
||||
- [ ] Scope is focused.
|
||||
- [ ] Tests or checks are listed.
|
||||
- [ ] Screenshots or recordings are included for UI changes.
|
||||
- [ ] Migration and deployment notes are included when relevant.
|
||||
- [ ] Risks and follow-ups are documented.
|
||||
- [ ] No secrets, debug code, or unrelated files are included.
|
||||
|
||||
## Release
|
||||
|
||||
- [ ] Release scope is defined.
|
||||
- [ ] Required checks passed.
|
||||
- [ ] Database migrations are reviewed.
|
||||
- [ ] Configuration and secrets are ready.
|
||||
- [ ] Rollback plan exists.
|
||||
- [ ] Monitoring and alerting are ready.
|
||||
- [ ] Stakeholders are informed.
|
||||
|
||||
## Production Readiness
|
||||
|
||||
- [ ] Runtime environments are documented.
|
||||
- [ ] Health checks exist.
|
||||
- [ ] Logs include correlation identifiers.
|
||||
- [ ] Backups and restore process are tested or scheduled.
|
||||
- [ ] Alerts cover availability and critical failures.
|
||||
- [ ] Security-critical settings are production-safe.
|
||||
- [ ] Operational runbooks exist for common failures.
|
||||
@@ -0,0 +1,210 @@
|
||||
# Conventions
|
||||
|
||||
This document defines project engineering standards. It should remain practical,
|
||||
specific, and enforceable.
|
||||
|
||||
For project facts, see [PROJECT.md](PROJECT.md).
|
||||
For architecture boundaries, see [ARCHITECTURE.md](ARCHITECTURE.md).
|
||||
For task quality gates, see [CHECKLISTS.md](CHECKLISTS.md).
|
||||
|
||||
## Naming
|
||||
|
||||
Use names that expose intent and domain meaning.
|
||||
|
||||
- Prefer domain terms over technical shorthand.
|
||||
- Avoid abbreviations unless they are widely understood in the project.
|
||||
- Name booleans as predicates, such as `isEnabled`, `hasPermission`, or
|
||||
`canRetry`.
|
||||
- Name commands by action and object, such as `CreateInvoice` or
|
||||
`syncCustomer`.
|
||||
- Name events in past tense when they represent something that happened.
|
||||
|
||||
Add language-specific naming rules here:
|
||||
|
||||
- `{{LANGUAGE_NAMING_RULE}}`
|
||||
|
||||
## File Organization
|
||||
|
||||
Files should have one clear responsibility.
|
||||
|
||||
- Keep files small enough to review comfortably.
|
||||
- Co-locate tests with the tested module when that matches the stack convention.
|
||||
- Separate generated files from hand-written source.
|
||||
- Avoid catch-all utility files that collect unrelated behavior.
|
||||
|
||||
Project-specific rules:
|
||||
|
||||
- `{{FILE_ORGANIZATION_RULE}}`
|
||||
|
||||
## Folder Organization
|
||||
|
||||
Folders should communicate ownership and architecture boundaries.
|
||||
|
||||
- Organize by feature or module when domain ownership matters.
|
||||
- Organize by technical layer only when it improves clarity for the project.
|
||||
- Keep public interfaces easy to find.
|
||||
- Keep infrastructure details out of domain folders unless deliberately chosen.
|
||||
|
||||
Project-specific folder map:
|
||||
|
||||
| Folder | Rule |
|
||||
| --- | --- |
|
||||
| `{{FOLDER}}` | `{{FOLDER_RULE}}` |
|
||||
|
||||
## Dependency Injection
|
||||
|
||||
Use dependency injection to make boundaries explicit and tests practical.
|
||||
|
||||
- Inject external resources, clocks, random generators, HTTP clients, file
|
||||
systems, queues, and database access.
|
||||
- Avoid service locators unless the framework requires them.
|
||||
- Keep object lifetimes explicit.
|
||||
- Do not inject dependencies that are pure values or local implementation
|
||||
details.
|
||||
|
||||
Project-specific DI rules:
|
||||
|
||||
- `{{DEPENDENCY_INJECTION_RULE}}`
|
||||
|
||||
## Logging
|
||||
|
||||
Logging should support operations and debugging without leaking sensitive data.
|
||||
|
||||
- Use structured logs when the platform supports them.
|
||||
- Include correlation or request identifiers.
|
||||
- Log decisions and external failures at meaningful boundaries.
|
||||
- Do not log secrets, access tokens, passwords, private keys, or full payment
|
||||
data.
|
||||
- Avoid noisy logs inside tight loops or high-volume paths.
|
||||
|
||||
Project-specific logging rules:
|
||||
|
||||
- `{{LOGGING_RULE}}`
|
||||
|
||||
## Validation
|
||||
|
||||
Validation should happen at the correct boundary.
|
||||
|
||||
- Validate transport shape at the interface boundary.
|
||||
- Validate business invariants in the domain or application layer.
|
||||
- Validate persistence constraints before relying on database failures for
|
||||
expected user errors.
|
||||
- Return actionable validation feedback where appropriate.
|
||||
|
||||
Project-specific validation rules:
|
||||
|
||||
- `{{VALIDATION_RULE}}`
|
||||
|
||||
## Error Handling
|
||||
|
||||
Errors should be explicit, observable, and safe.
|
||||
|
||||
- Use typed or structured errors where the language supports them.
|
||||
- Do not swallow exceptions without a recovery path.
|
||||
- Map internal errors to stable user-facing or client-facing responses.
|
||||
- Preserve diagnostic context for logs.
|
||||
- Avoid exposing stack traces or implementation details to users.
|
||||
|
||||
Project-specific error rules:
|
||||
|
||||
- `{{ERROR_HANDLING_RULE}}`
|
||||
|
||||
## DTO Rules
|
||||
|
||||
DTOs represent boundary contracts.
|
||||
|
||||
- Keep DTOs separate from domain models when they change for different reasons.
|
||||
- Do not put business rules in DTOs.
|
||||
- Version public contracts deliberately.
|
||||
- Validate DTO shape before mapping to domain commands or queries.
|
||||
- Avoid leaking persistence models through public APIs.
|
||||
|
||||
Project-specific DTO rules:
|
||||
|
||||
- `{{DTO_RULE}}`
|
||||
|
||||
## Repository Rules
|
||||
|
||||
Repositories, gateways, or data access abstractions should express persistence
|
||||
intent without hiding important consistency behavior.
|
||||
|
||||
- Keep query methods specific enough to reveal purpose.
|
||||
- Avoid generic repositories when they obscure domain behavior.
|
||||
- Document transaction boundaries.
|
||||
- Make idempotency explicit for write operations where retries are possible.
|
||||
|
||||
Project-specific repository rules:
|
||||
|
||||
- `{{REPOSITORY_RULE}}`
|
||||
|
||||
## Service Rules
|
||||
|
||||
Services should coordinate use cases, not become unbounded containers.
|
||||
|
||||
- Prefer cohesive application services around use cases.
|
||||
- Keep domain rules in domain objects or domain services.
|
||||
- Keep infrastructure calls behind clear interfaces.
|
||||
- Avoid services named only after technical actions such as `Manager`,
|
||||
`Helper`, or `Processor` unless the meaning is precise in context.
|
||||
|
||||
Project-specific service rules:
|
||||
|
||||
- `{{SERVICE_RULE}}`
|
||||
|
||||
## Testing
|
||||
|
||||
Tests should match risk and behavior.
|
||||
|
||||
- Unit test domain logic and pure transformations.
|
||||
- Integration test database, queue, file, network, and framework boundaries.
|
||||
- End-to-end test critical user journeys.
|
||||
- Regression test bugs before or with the fix.
|
||||
- Keep tests deterministic and independent where practical.
|
||||
|
||||
Project-specific testing rules:
|
||||
|
||||
- `{{TESTING_RULE}}`
|
||||
|
||||
## Git Workflow
|
||||
|
||||
Use [branching.md](branching.md) for branch strategy.
|
||||
|
||||
Default expectations:
|
||||
|
||||
- Keep commits focused and reviewable.
|
||||
- Write commit messages that describe the reason and outcome.
|
||||
- Rebase or merge according to the project branch policy.
|
||||
- Do not mix unrelated refactors with behavior changes.
|
||||
|
||||
## Pull Requests
|
||||
|
||||
Pull requests should explain what changed, why it changed, and how it was
|
||||
validated.
|
||||
|
||||
Recommended PR sections:
|
||||
|
||||
- Summary.
|
||||
- Scope.
|
||||
- Validation.
|
||||
- Risks.
|
||||
- Screenshots or recordings for UI changes.
|
||||
- Migration or deployment notes when relevant.
|
||||
|
||||
Use [CHECKLISTS.md](CHECKLISTS.md) before requesting review.
|
||||
|
||||
## Code Reviews
|
||||
|
||||
Reviews should prioritize correctness and maintainability.
|
||||
|
||||
Review for:
|
||||
|
||||
- Behavior and edge cases.
|
||||
- Security and authorization.
|
||||
- Data integrity.
|
||||
- Architecture boundaries.
|
||||
- Test quality.
|
||||
- Operational impact.
|
||||
- Readability.
|
||||
|
||||
Style comments should reference documented conventions or automated tooling
|
||||
where possible.
|
||||
@@ -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.
|
||||
+185
@@ -0,0 +1,185 @@
|
||||
# Project
|
||||
|
||||
This document is the source of truth for project intent, scope, runtime facts,
|
||||
and operational expectations.
|
||||
|
||||
For implementation structure, see [ARCHITECTURE.md](ARCHITECTURE.md).
|
||||
For engineering standards, see [CONVENTIONS.md](CONVENTIONS.md).
|
||||
For delivery workflow, see [workflow.md](workflow.md).
|
||||
|
||||
## Project Identity
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Project name | `{{PROJECT_NAME}}` |
|
||||
| Repository | `{{REPOSITORY_URL}}` |
|
||||
| Primary owner | `{{OWNER}}` |
|
||||
| Status | `{{STATUS}}` |
|
||||
| Target users | `{{TARGET_USERS}}` |
|
||||
|
||||
## Vision
|
||||
|
||||
`{{PROJECT_VISION}}`
|
||||
|
||||
Describe the long-term purpose of the project in one or two paragraphs.
|
||||
The vision should explain why the project exists, not how it is implemented.
|
||||
|
||||
## Goals
|
||||
|
||||
- `{{GOAL_1}}`
|
||||
- `{{GOAL_2}}`
|
||||
- `{{GOAL_3}}`
|
||||
|
||||
Goals should be measurable enough to guide trade-offs.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- `{{NON_GOAL_1}}`
|
||||
- `{{NON_GOAL_2}}`
|
||||
|
||||
Non-goals prevent accidental scope expansion.
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
| ID | Requirement | Priority | Status |
|
||||
| --- | --- | --- | --- |
|
||||
| FR-001 | `{{FUNCTIONAL_REQUIREMENT}}` | Must | Proposed |
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
| Category | Requirement | Measurement |
|
||||
| --- | --- | --- |
|
||||
| Availability | `{{AVAILABILITY_REQUIREMENT}}` | `{{AVAILABILITY_MEASURE}}` |
|
||||
| Performance | `{{PERFORMANCE_REQUIREMENT}}` | `{{PERFORMANCE_MEASURE}}` |
|
||||
| Security | `{{SECURITY_REQUIREMENT}}` | `{{SECURITY_MEASURE}}` |
|
||||
| Privacy | `{{PRIVACY_REQUIREMENT}}` | `{{PRIVACY_MEASURE}}` |
|
||||
| Maintainability | `{{MAINTAINABILITY_REQUIREMENT}}` | `{{MAINTAINABILITY_MEASURE}}` |
|
||||
|
||||
## Users And Roles
|
||||
|
||||
| Role | Description | Key Permissions |
|
||||
| --- | --- | --- |
|
||||
| `{{ROLE_NAME}}` | `{{ROLE_DESCRIPTION}}` | `{{ROLE_PERMISSIONS}}` |
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Area | Choice | Notes |
|
||||
| --- | --- | --- |
|
||||
| Language | `{{LANGUAGE}}` | `{{LANGUAGE_NOTES}}` |
|
||||
| Framework | `{{FRAMEWORK}}` | `{{FRAMEWORK_NOTES}}` |
|
||||
| Frontend | `{{FRONTEND}}` | `{{FRONTEND_NOTES}}` |
|
||||
| Backend | `{{BACKEND}}` | `{{BACKEND_NOTES}}` |
|
||||
| Database | `{{DATABASE}}` | `{{DATABASE_NOTES}}` |
|
||||
| Messaging | `{{MESSAGING}}` | `{{MESSAGING_NOTES}}` |
|
||||
| Search | `{{SEARCH}}` | `{{SEARCH_NOTES}}` |
|
||||
| Cache | `{{CACHE}}` | `{{CACHE_NOTES}}` |
|
||||
|
||||
## Runtime
|
||||
|
||||
| Environment | Purpose | URL or Entry Point | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| Local | Development | `{{LOCAL_URL}}` | `{{LOCAL_NOTES}}` |
|
||||
| Test | Automated validation | `{{TEST_URL}}` | `{{TEST_NOTES}}` |
|
||||
| Staging | Release verification | `{{STAGING_URL}}` | `{{STAGING_NOTES}}` |
|
||||
| Production | Live system | `{{PRODUCTION_URL}}` | `{{PRODUCTION_NOTES}}` |
|
||||
|
||||
## Frameworks
|
||||
|
||||
Document framework-specific expectations here only when they affect how the
|
||||
project is built, tested, deployed, or maintained.
|
||||
|
||||
- `{{FRAMEWORK_CONSTRAINT}}`
|
||||
- `{{FRAMEWORK_EXTENSION_POINT}}`
|
||||
|
||||
## Infrastructure
|
||||
|
||||
| Component | Provider | Responsibility | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| Hosting | `{{HOSTING_PROVIDER}}` | `{{HOSTING_RESPONSIBILITY}}` | `{{HOSTING_NOTES}}` |
|
||||
| Storage | `{{STORAGE_PROVIDER}}` | `{{STORAGE_RESPONSIBILITY}}` | `{{STORAGE_NOTES}}` |
|
||||
| Network | `{{NETWORK_PROVIDER}}` | `{{NETWORK_RESPONSIBILITY}}` | `{{NETWORK_NOTES}}` |
|
||||
|
||||
## Database
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Database engine | `{{DATABASE}}` |
|
||||
| Migration tool | `{{MIGRATION_TOOL}}` |
|
||||
| Backup strategy | `{{BACKUP_STRATEGY}}` |
|
||||
| Restore strategy | `{{RESTORE_STRATEGY}}` |
|
||||
| Data retention | `{{DATA_RETENTION}}` |
|
||||
|
||||
## CI/CD
|
||||
|
||||
| Pipeline | Trigger | Required Checks | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `{{PIPELINE_NAME}}` | `{{PIPELINE_TRIGGER}}` | `{{PIPELINE_CHECKS}}` | `{{PIPELINE_NOTES}}` |
|
||||
|
||||
## Deployment
|
||||
|
||||
| Area | Policy |
|
||||
| --- | --- |
|
||||
| Deployment strategy | `{{DEPLOYMENT}}` |
|
||||
| Rollback strategy | `{{ROLLBACK_STRATEGY}}` |
|
||||
| Release owner | `{{RELEASE_OWNER}}` |
|
||||
| Change window | `{{CHANGE_WINDOW}}` |
|
||||
|
||||
See [release-process.md](release-process.md) for release execution.
|
||||
|
||||
## Authentication
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Authentication method | `{{AUTHENTICATION_METHOD}}` |
|
||||
| Identity provider | `{{IDENTITY_PROVIDER}}` |
|
||||
| Session model | `{{SESSION_MODEL}}` |
|
||||
| Token lifetime | `{{TOKEN_LIFETIME}}` |
|
||||
|
||||
## Authorization
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Authorization model | `{{AUTHORIZATION_MODEL}}` |
|
||||
| Role source | `{{ROLE_SOURCE}}` |
|
||||
| Policy location | `{{POLICY_LOCATION}}` |
|
||||
| Audit requirements | `{{AUTHORIZATION_AUDIT_REQUIREMENTS}}` |
|
||||
|
||||
## Logging
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Logging library | `{{LOGGING_LIBRARY}}` |
|
||||
| Log sink | `{{LOG_SINK}}` |
|
||||
| Correlation ID | `{{CORRELATION_ID_POLICY}}` |
|
||||
| Sensitive data policy | `{{LOG_SENSITIVE_DATA_POLICY}}` |
|
||||
|
||||
## Monitoring
|
||||
|
||||
| Signal | Tool | Alert Policy |
|
||||
| --- | --- | --- |
|
||||
| Availability | `{{AVAILABILITY_TOOL}}` | `{{AVAILABILITY_ALERT_POLICY}}` |
|
||||
| Errors | `{{ERROR_TOOL}}` | `{{ERROR_ALERT_POLICY}}` |
|
||||
| Performance | `{{PERFORMANCE_TOOL}}` | `{{PERFORMANCE_ALERT_POLICY}}` |
|
||||
| Business metrics | `{{BUSINESS_METRICS_TOOL}}` | `{{BUSINESS_ALERT_POLICY}}` |
|
||||
|
||||
## Testing
|
||||
|
||||
| Test Type | Tooling | Required When |
|
||||
| --- | --- | --- |
|
||||
| Unit | `{{UNIT_TEST_TOOL}}` | `{{UNIT_TEST_POLICY}}` |
|
||||
| Integration | `{{INTEGRATION_TEST_TOOL}}` | `{{INTEGRATION_TEST_POLICY}}` |
|
||||
| End-to-end | `{{E2E_TEST_TOOL}}` | `{{E2E_TEST_POLICY}}` |
|
||||
| Performance | `{{PERFORMANCE_TEST_TOOL}}` | `{{PERFORMANCE_TEST_POLICY}}` |
|
||||
| Security | `{{SECURITY_TEST_TOOL}}` | `{{SECURITY_TEST_POLICY}}` |
|
||||
|
||||
## Roadmap
|
||||
|
||||
| Milestone | Target | Outcome |
|
||||
| --- | --- | --- |
|
||||
| `{{MILESTONE}}` | `{{TARGET_DATE}}` | `{{OUTCOME}}` |
|
||||
|
||||
## Open Questions
|
||||
|
||||
| Question | Owner | Needed By | Status |
|
||||
| --- | --- | --- | --- |
|
||||
| `{{OPEN_QUESTION}}` | `{{QUESTION_OWNER}}` | `{{NEEDED_BY}}` | Open |
|
||||
+310
@@ -0,0 +1,310 @@
|
||||
# Prompts
|
||||
|
||||
This file is a reusable engineering prompt library for humans and AI coding
|
||||
agents.
|
||||
|
||||
Use these prompts together with [AGENTS.md](../AGENTS.md),
|
||||
[PROJECT.md](PROJECT.md), [ARCHITECTURE.md](ARCHITECTURE.md), and
|
||||
[CONVENTIONS.md](CONVENTIONS.md).
|
||||
|
||||
## Prompt Pattern
|
||||
|
||||
Strong prompts include:
|
||||
|
||||
- Objective.
|
||||
- Relevant files, URLs, tickets, or logs.
|
||||
- Constraints and non-goals.
|
||||
- Expected output.
|
||||
- Validation expectations.
|
||||
- Whether the agent should implement, plan only, or review only.
|
||||
|
||||
## Feature Development
|
||||
|
||||
```text
|
||||
Act as a senior software engineer in this repository.
|
||||
|
||||
Objective:
|
||||
Implement {{FEATURE_NAME}}.
|
||||
|
||||
Context:
|
||||
- Product goal: {{PRODUCT_GOAL}}
|
||||
- Relevant docs: docs/PROJECT.md, docs/ARCHITECTURE.md, docs/CONVENTIONS.md
|
||||
- Relevant files: {{RELEVANT_FILES}}
|
||||
|
||||
Requirements:
|
||||
- {{REQUIREMENT_1}}
|
||||
- {{REQUIREMENT_2}}
|
||||
|
||||
Non-goals:
|
||||
- {{NON_GOAL_1}}
|
||||
|
||||
Before coding:
|
||||
- Inspect the current implementation.
|
||||
- Identify ambiguity.
|
||||
- Ask concise questions if confidence is below 95%.
|
||||
|
||||
After coding:
|
||||
- Run the strongest practical validation.
|
||||
- Summarize changed files, validation, and residual risk.
|
||||
```
|
||||
|
||||
## Bug Investigation
|
||||
|
||||
```text
|
||||
Investigate this bug before changing code.
|
||||
|
||||
Observed behavior:
|
||||
{{OBSERVED_BEHAVIOR}}
|
||||
|
||||
Expected behavior:
|
||||
{{EXPECTED_BEHAVIOR}}
|
||||
|
||||
Evidence:
|
||||
{{LOGS_SCREENSHOTS_OR_STEPS}}
|
||||
|
||||
Task:
|
||||
- Reproduce or reason from available evidence.
|
||||
- Identify the most likely root cause.
|
||||
- Locate the affected code path.
|
||||
- Propose the smallest maintainable fix.
|
||||
- Implement only after the cause is understood.
|
||||
- Add or update regression coverage where practical.
|
||||
```
|
||||
|
||||
## Root Cause Analysis
|
||||
|
||||
```text
|
||||
Perform a root cause analysis for {{INCIDENT_OR_DEFECT}}.
|
||||
|
||||
Include:
|
||||
- Timeline.
|
||||
- User impact.
|
||||
- Technical trigger.
|
||||
- Root cause.
|
||||
- Contributing factors.
|
||||
- Detection gap.
|
||||
- Corrective actions.
|
||||
- Preventive actions.
|
||||
|
||||
Separate confirmed facts from hypotheses.
|
||||
Do not assign blame to individuals.
|
||||
```
|
||||
|
||||
## Refactoring
|
||||
|
||||
```text
|
||||
Refactor {{AREA}} to improve {{QUALITY_GOAL}}.
|
||||
|
||||
Constraints:
|
||||
- Preserve behavior.
|
||||
- Keep public contracts stable unless explicitly approved.
|
||||
- Avoid broad unrelated cleanup.
|
||||
- Follow docs/ARCHITECTURE.md and docs/CONVENTIONS.md.
|
||||
|
||||
Process:
|
||||
- Inspect existing patterns.
|
||||
- Identify tests or checks that protect behavior.
|
||||
- Make small mechanical changes first.
|
||||
- Run validation after meaningful steps.
|
||||
- Summarize behavior-preservation evidence.
|
||||
```
|
||||
|
||||
## Architecture Review
|
||||
|
||||
```text
|
||||
Review the architecture of {{SYSTEM_OR_MODULE}}.
|
||||
|
||||
Use:
|
||||
- docs/PROJECT.md
|
||||
- docs/ARCHITECTURE.md
|
||||
- docs/DECISIONS.md
|
||||
- Relevant source files
|
||||
|
||||
Focus on:
|
||||
- Boundary clarity.
|
||||
- Dependency direction.
|
||||
- Data ownership.
|
||||
- Failure modes.
|
||||
- Security assumptions.
|
||||
- Operational complexity.
|
||||
- Maintainability over the next {{TIME_HORIZON}}.
|
||||
|
||||
Return:
|
||||
- Findings ordered by severity.
|
||||
- Trade-offs.
|
||||
- Recommended decisions or ADR updates.
|
||||
```
|
||||
|
||||
## Security Review
|
||||
|
||||
```text
|
||||
Perform a security review of {{SCOPE}}.
|
||||
|
||||
Focus on:
|
||||
- Authentication.
|
||||
- Authorization.
|
||||
- Input validation.
|
||||
- Output encoding.
|
||||
- Secrets handling.
|
||||
- Data exposure.
|
||||
- Dependency risk.
|
||||
- Logging of sensitive data.
|
||||
- SSRF, injection, XSS, CSRF, path traversal, and insecure deserialization where relevant.
|
||||
|
||||
For each finding include:
|
||||
- Impact.
|
||||
- Exploitability.
|
||||
- Evidence.
|
||||
- Recommended fix.
|
||||
- Validation strategy.
|
||||
```
|
||||
|
||||
## Performance Review
|
||||
|
||||
```text
|
||||
Review performance risk in {{SCOPE}}.
|
||||
|
||||
Include:
|
||||
- Hot paths.
|
||||
- Algorithmic complexity.
|
||||
- Database query behavior.
|
||||
- Caching behavior.
|
||||
- Network calls.
|
||||
- Rendering or UI bottlenecks.
|
||||
- Resource usage.
|
||||
- Measurement gaps.
|
||||
|
||||
Recommend improvements only when they are justified by evidence, constraints, or clear risk.
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
```text
|
||||
Improve documentation for {{AREA}}.
|
||||
|
||||
Goals:
|
||||
- Make setup and maintenance easier.
|
||||
- Remove outdated or duplicated information.
|
||||
- Add cross links to related docs.
|
||||
- Keep one source of truth per topic.
|
||||
|
||||
Validate:
|
||||
- Links are correct.
|
||||
- Commands are current.
|
||||
- Examples are realistic.
|
||||
- The document is useful to a new contributor.
|
||||
```
|
||||
|
||||
## API Design
|
||||
|
||||
```text
|
||||
Design or review the API for {{CAPABILITY}}.
|
||||
|
||||
Include:
|
||||
- Consumers.
|
||||
- Resource or command model.
|
||||
- Request and response shapes.
|
||||
- Validation errors.
|
||||
- Authorization rules.
|
||||
- Idempotency.
|
||||
- Pagination or filtering.
|
||||
- Versioning.
|
||||
- Backward compatibility.
|
||||
- Observability.
|
||||
|
||||
Prefer stable contracts over exposing internal persistence models.
|
||||
```
|
||||
|
||||
## Database Design
|
||||
|
||||
```text
|
||||
Design or review database changes for {{CAPABILITY}}.
|
||||
|
||||
Include:
|
||||
- Entities and ownership.
|
||||
- Relationships.
|
||||
- Constraints.
|
||||
- Indexes.
|
||||
- Migration strategy.
|
||||
- Rollback strategy.
|
||||
- Backfill needs.
|
||||
- Data retention.
|
||||
- Privacy concerns.
|
||||
- Query patterns.
|
||||
|
||||
Do not implement destructive migrations without explicit approval.
|
||||
```
|
||||
|
||||
## Test Generation
|
||||
|
||||
```text
|
||||
Generate tests for {{SCOPE}}.
|
||||
|
||||
Use the repository's existing test patterns.
|
||||
|
||||
Cover:
|
||||
- Happy path.
|
||||
- Boundary conditions.
|
||||
- Authorization or permission behavior when relevant.
|
||||
- Error handling.
|
||||
- Regression cases.
|
||||
|
||||
Avoid brittle tests that depend on incidental implementation details.
|
||||
```
|
||||
|
||||
## Code Review
|
||||
|
||||
```text
|
||||
Review the provided changes as a senior engineer.
|
||||
|
||||
Prioritize:
|
||||
- Bugs.
|
||||
- Security issues.
|
||||
- Data loss risk.
|
||||
- Behavioral regressions.
|
||||
- Missing validation.
|
||||
- Maintainability issues.
|
||||
|
||||
Return findings first, ordered by severity, with file and line references where available.
|
||||
Keep summary secondary.
|
||||
```
|
||||
|
||||
## Pull Request Review
|
||||
|
||||
```text
|
||||
Review this pull request.
|
||||
|
||||
Use:
|
||||
- PR description.
|
||||
- Diff.
|
||||
- Linked issue or requirement.
|
||||
- Relevant project docs.
|
||||
|
||||
Assess:
|
||||
- Whether the change solves the stated problem.
|
||||
- Whether the implementation fits the architecture.
|
||||
- Whether tests and validation match the risk.
|
||||
- Whether rollout or migration notes are missing.
|
||||
|
||||
Return:
|
||||
- Blocking findings.
|
||||
- Non-blocking suggestions.
|
||||
- Questions.
|
||||
- Merge readiness.
|
||||
```
|
||||
|
||||
## Technical Debt Review
|
||||
|
||||
```text
|
||||
Assess technical debt in {{SCOPE}}.
|
||||
|
||||
Classify findings by:
|
||||
- User impact.
|
||||
- Engineering drag.
|
||||
- Risk.
|
||||
- Estimated effort.
|
||||
- Suggested sequencing.
|
||||
|
||||
Do not recommend rewrites unless incremental improvement is clearly worse.
|
||||
Prefer concrete next steps over broad critique.
|
||||
```
|
||||
@@ -0,0 +1,111 @@
|
||||
# Branching Strategy
|
||||
|
||||
This document defines the default Git branching strategy.
|
||||
|
||||
For delivery workflow, see [workflow.md](workflow.md).
|
||||
For pull request expectations, see [CONVENTIONS.md](CONVENTIONS.md#pull-requests).
|
||||
|
||||
## Default Model
|
||||
|
||||
Use a simple trunk-based model unless the project has a clear reason to add
|
||||
long-lived release branches.
|
||||
|
||||
```mermaid
|
||||
gitGraph
|
||||
commit id: "main"
|
||||
branch feature
|
||||
checkout feature
|
||||
commit id: "work"
|
||||
commit id: "validate"
|
||||
checkout main
|
||||
merge feature
|
||||
commit id: "release"
|
||||
```
|
||||
|
||||
## Branch Types
|
||||
|
||||
| Type | Pattern | Purpose |
|
||||
| --- | --- | --- |
|
||||
| Feature | `feature/{{short-description}}` | New user-facing or system capability. |
|
||||
| Bug fix | `fix/{{short-description}}` | Defect correction. |
|
||||
| Refactor | `refactor/{{short-description}}` | Behavior-preserving structural improvement. |
|
||||
| Documentation | `docs/{{short-description}}` | Documentation-only changes. |
|
||||
| Chore | `chore/{{short-description}}` | Maintenance work with no product behavior change. |
|
||||
| Release | `release/{{version}}` | Optional stabilization branch for release trains. |
|
||||
| Hotfix | `hotfix/{{short-description}}` | Urgent production correction. |
|
||||
|
||||
## Main Branch
|
||||
|
||||
The `main` branch should remain deployable or releasable according to the
|
||||
project's release model.
|
||||
|
||||
Minimum expectations:
|
||||
|
||||
- Required checks pass.
|
||||
- Changes are reviewed when the project requires review.
|
||||
- Risky migrations and config changes are documented.
|
||||
- Direct pushes are limited to repository maintainers or automation.
|
||||
|
||||
## Feature Branches
|
||||
|
||||
Feature branches should be short lived.
|
||||
|
||||
- Keep scope focused.
|
||||
- Rebase or merge from `main` according to project policy.
|
||||
- Delete branches after merge.
|
||||
- Avoid stacking unrelated changes.
|
||||
|
||||
## Release Branches
|
||||
|
||||
Use release branches only when needed for stabilization, compliance, or release
|
||||
train coordination.
|
||||
|
||||
Release branches should receive:
|
||||
|
||||
- Critical fixes.
|
||||
- Release documentation.
|
||||
- Version updates.
|
||||
- No unrelated refactors.
|
||||
|
||||
## Hotfixes
|
||||
|
||||
Hotfixes should prioritize production restoration.
|
||||
|
||||
Process:
|
||||
|
||||
1. Create a hotfix branch from the deployed commit or release branch.
|
||||
2. Apply the smallest safe fix.
|
||||
3. Validate the specific failure path.
|
||||
4. Release.
|
||||
5. Merge the hotfix back into `main`.
|
||||
6. Add follow-up work for broader cleanup if needed.
|
||||
|
||||
## Commit Messages
|
||||
|
||||
Use meaningful commit messages that explain the outcome.
|
||||
|
||||
Recommended format:
|
||||
|
||||
```text
|
||||
{{type}}: {{short imperative summary}}
|
||||
|
||||
{{optional context, rationale, or validation notes}}
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `docs: add starter architecture guide`
|
||||
- `fix: prevent duplicate invoice submission`
|
||||
- `refactor: isolate payment gateway retries`
|
||||
|
||||
## Merge Policy
|
||||
|
||||
Choose one policy per project:
|
||||
|
||||
| Policy | Best When |
|
||||
| --- | --- |
|
||||
| Squash merge | Small teams want clean history and one commit per PR. |
|
||||
| Merge commit | Teams want to preserve branch context. |
|
||||
| Rebase merge | Teams want linear history with individual commits. |
|
||||
|
||||
Record the selected policy in [PROJECT.md](PROJECT.md) or this file.
|
||||
@@ -0,0 +1,98 @@
|
||||
# Release Process
|
||||
|
||||
This document defines the default release process.
|
||||
|
||||
For daily delivery flow, see [workflow.md](workflow.md).
|
||||
For branch policy, see [branching.md](branching.md).
|
||||
For release checklist, see [CHECKLISTS.md](CHECKLISTS.md#release).
|
||||
|
||||
## Release Principles
|
||||
|
||||
- Release small changes when practical.
|
||||
- Prefer repeatable automation over manual steps.
|
||||
- Validate before and after deployment.
|
||||
- Keep rollback or recovery options ready.
|
||||
- Record production-impacting decisions.
|
||||
|
||||
## Release Types
|
||||
|
||||
| Type | Description | Example |
|
||||
| --- | --- | --- |
|
||||
| Standard | Planned release through the normal pipeline. | Weekly feature release. |
|
||||
| Hotfix | Urgent production fix. | Authorization regression fix. |
|
||||
| Experimental | Limited rollout or feature flag release. | Beta feature for selected users. |
|
||||
| Infrastructure | Runtime, hosting, network, or dependency change. | Database engine upgrade. |
|
||||
|
||||
## Versioning
|
||||
|
||||
Choose the versioning model that matches the project:
|
||||
|
||||
- Semantic versioning for libraries, APIs, SDKs, and installable packages.
|
||||
- Calendar versioning for operational products with frequent releases.
|
||||
- Build numbers or commit SHAs for internal services.
|
||||
|
||||
Document the chosen model in [PROJECT.md](PROJECT.md).
|
||||
|
||||
## Readiness
|
||||
|
||||
Before release:
|
||||
|
||||
- Scope is confirmed.
|
||||
- Required checks pass.
|
||||
- Migrations are reviewed.
|
||||
- Configuration is ready.
|
||||
- Secrets are present in the target environment.
|
||||
- Rollback or recovery plan exists.
|
||||
- Monitoring is available.
|
||||
- Stakeholders know the release window when needed.
|
||||
|
||||
## Deployment
|
||||
|
||||
Deployment steps:
|
||||
|
||||
1. Confirm target environment.
|
||||
2. Confirm release version or commit.
|
||||
3. Run pre-deploy checks.
|
||||
4. Deploy.
|
||||
5. Run migrations when required by the release plan.
|
||||
6. Run smoke tests.
|
||||
7. Monitor health and error signals.
|
||||
8. Announce completion or rollback.
|
||||
|
||||
## Smoke Tests
|
||||
|
||||
Smoke tests should prove that the release is alive and the most important path
|
||||
works.
|
||||
|
||||
Examples:
|
||||
|
||||
- Health endpoint returns success.
|
||||
- Application loads.
|
||||
- Login works.
|
||||
- Critical API endpoint succeeds.
|
||||
- Background worker starts.
|
||||
- Database connectivity is healthy.
|
||||
|
||||
## Rollback And Recovery
|
||||
|
||||
Rollback planning should address:
|
||||
|
||||
- Application artifact rollback.
|
||||
- Database migration rollback or forward fix.
|
||||
- Configuration rollback.
|
||||
- Feature flag disablement.
|
||||
- Queue or job replay behavior.
|
||||
- External dependency failure.
|
||||
|
||||
If database changes are not reversible, document the recovery path before
|
||||
deployment.
|
||||
|
||||
## Post-Release Review
|
||||
|
||||
After release:
|
||||
|
||||
- Confirm monitoring is quiet or expected.
|
||||
- Record incidents or anomalies.
|
||||
- Update docs if release steps drifted.
|
||||
- Add follow-up tasks for manual work discovered during release.
|
||||
- Capture lessons in checklists or ADRs when they change future behavior.
|
||||
@@ -0,0 +1,104 @@
|
||||
# Repository Setup
|
||||
|
||||
This document explains how to use the Engineering Starter Kit for a new project.
|
||||
|
||||
For the recommended documentation flow, see [../README.md](../README.md).
|
||||
For the AI-agent contract, see [../AGENTS.md](../AGENTS.md).
|
||||
|
||||
## Bootstrap Options
|
||||
|
||||
Choose one:
|
||||
|
||||
| Option | Use When |
|
||||
| --- | --- |
|
||||
| Copy repository | You want a simple starting point without preserving starter-kit history. |
|
||||
| Template repository | Your Git host supports creating repositories from a template. |
|
||||
| Subtree or vendor copy | You want to periodically pull updates from this kit. |
|
||||
|
||||
Do not use this starter kit as a runtime dependency. It is project scaffolding
|
||||
and documentation architecture.
|
||||
|
||||
## Initial Setup
|
||||
|
||||
1. Create the new repository.
|
||||
2. Copy the starter-kit files.
|
||||
3. Replace placeholder values such as `{{PROJECT_NAME}}`, `{{LANGUAGE}}`,
|
||||
`{{FRAMEWORK}}`, `{{DATABASE}}`, and `{{DEPLOYMENT}}`.
|
||||
4. Delete sections that are not relevant to the project.
|
||||
5. Add project-specific setup commands.
|
||||
6. Commit the initialized documentation before major implementation work.
|
||||
|
||||
## Recommended First Commit
|
||||
|
||||
The first commit should establish:
|
||||
|
||||
- `README.md`.
|
||||
- `AGENTS.md`.
|
||||
- `docs/PROJECT.md`.
|
||||
- `docs/ARCHITECTURE.md`.
|
||||
- `docs/CONVENTIONS.md`.
|
||||
- `docs/DECISIONS.md`.
|
||||
- `.gitignore`.
|
||||
- Tooling or source skeleton if already known.
|
||||
|
||||
## Project-Specific Customization
|
||||
|
||||
Update these files first:
|
||||
|
||||
| File | Required Customization |
|
||||
| --- | --- |
|
||||
| [PROJECT.md](PROJECT.md) | Vision, requirements, stack, environments, operations, and roadmap. |
|
||||
| [ARCHITECTURE.md](ARCHITECTURE.md) | Architecture style, folder structure, module boundaries, and flows. |
|
||||
| [CONVENTIONS.md](CONVENTIONS.md) | Language, framework, testing, review, and repository-specific rules. |
|
||||
| [DECISIONS.md](DECISIONS.md) | Accepted project decisions. Remove examples when real ADRs exist. |
|
||||
| [workflow.md](workflow.md) | Delivery steps, required checks, and review expectations. |
|
||||
| [branching.md](branching.md) | Branch naming and merge policy. |
|
||||
| [release-process.md](release-process.md) | Release, rollback, and monitoring expectations. |
|
||||
|
||||
## Placeholder Policy
|
||||
|
||||
Before a project is considered initialized:
|
||||
|
||||
- Replace placeholders when the answer is known.
|
||||
- Keep placeholders only when the unknown is intentional.
|
||||
- Track important unknowns in [PROJECT.md](PROJECT.md#open-questions).
|
||||
- Do not leave placeholders in public-facing documentation.
|
||||
|
||||
## AI Agent Setup
|
||||
|
||||
For AI-assisted projects:
|
||||
|
||||
1. Keep [../AGENTS.md](../AGENTS.md) at the repository root.
|
||||
2. Tell agents to read `AGENTS.md` before making changes.
|
||||
3. Keep architecture and conventions current enough for agents to follow them.
|
||||
4. Require final summaries to include changed files, validation, and risk.
|
||||
|
||||
## Documentation Review
|
||||
|
||||
After setup:
|
||||
|
||||
- Check every relative link.
|
||||
- Remove duplicated guidance.
|
||||
- Verify each document has one responsibility.
|
||||
- Confirm examples are marked as examples.
|
||||
- Confirm project-specific docs do not describe the starter kit itself.
|
||||
|
||||
## When To Add More Documents
|
||||
|
||||
Add a new document only when:
|
||||
|
||||
- The topic is durable.
|
||||
- The topic has a clear owner or responsibility.
|
||||
- The content would otherwise make another document unfocused.
|
||||
- The document will be maintained.
|
||||
|
||||
Good candidates:
|
||||
|
||||
- `docs/security.md`
|
||||
- `docs/operations.md`
|
||||
- `docs/api.md`
|
||||
- `docs/testing.md`
|
||||
- `docs/runbooks/`
|
||||
|
||||
Avoid creating documents for temporary plans that belong in issues or pull
|
||||
requests.
|
||||
@@ -0,0 +1,120 @@
|
||||
# Development Workflow
|
||||
|
||||
This document defines the default path from idea to released change.
|
||||
|
||||
For branch policy, see [branching.md](branching.md).
|
||||
For release execution, see [release-process.md](release-process.md).
|
||||
For task quality gates, see [CHECKLISTS.md](CHECKLISTS.md).
|
||||
|
||||
## Workflow Overview
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Idea["Idea or Issue"]
|
||||
Clarify["Clarify Scope"]
|
||||
Design["Design or Plan"]
|
||||
Implement["Implement"]
|
||||
Validate["Validate"]
|
||||
Review["Review"]
|
||||
Merge["Merge"]
|
||||
Release["Release"]
|
||||
Learn["Review Outcome"]
|
||||
|
||||
Idea --> Clarify
|
||||
Clarify --> Design
|
||||
Design --> Implement
|
||||
Implement --> Validate
|
||||
Validate --> Review
|
||||
Review --> Merge
|
||||
Merge --> Release
|
||||
Release --> Learn
|
||||
```
|
||||
|
||||
## 1. Clarify Scope
|
||||
|
||||
Before implementation:
|
||||
|
||||
- Define the objective.
|
||||
- Identify users or systems affected.
|
||||
- Confirm acceptance criteria.
|
||||
- Identify non-goals.
|
||||
- Note security, data, migration, and deployment risk.
|
||||
|
||||
If the task is ambiguous, resolve ambiguity before writing code.
|
||||
|
||||
## 2. Design Or Plan
|
||||
|
||||
Use a lightweight plan for most changes.
|
||||
|
||||
Create or update an ADR in [DECISIONS.md](DECISIONS.md) when the change affects:
|
||||
|
||||
- Architecture style.
|
||||
- Module boundaries.
|
||||
- Data ownership.
|
||||
- Security model.
|
||||
- Deployment strategy.
|
||||
- Public contracts.
|
||||
- Long-term operating cost.
|
||||
|
||||
## 3. Implement
|
||||
|
||||
Implementation expectations:
|
||||
|
||||
- Work in a focused branch unless the project policy says otherwise.
|
||||
- Read existing code before editing.
|
||||
- Follow [CONVENTIONS.md](CONVENTIONS.md).
|
||||
- Keep commits logically grouped.
|
||||
- Update documentation with behavior, setup, or architecture changes.
|
||||
|
||||
## 4. Validate
|
||||
|
||||
Use the strongest practical validation for the change:
|
||||
|
||||
- Build or type checks.
|
||||
- Unit tests.
|
||||
- Integration tests.
|
||||
- End-to-end tests.
|
||||
- Manual UI or API checks.
|
||||
- Documentation link checks.
|
||||
|
||||
Record validation evidence in the pull request or final work summary.
|
||||
|
||||
## 5. Review
|
||||
|
||||
Review should answer:
|
||||
|
||||
- Does the change solve the stated problem?
|
||||
- Is it consistent with [ARCHITECTURE.md](ARCHITECTURE.md)?
|
||||
- Does it follow [CONVENTIONS.md](CONVENTIONS.md)?
|
||||
- Are risks and rollback needs clear?
|
||||
- Is validation sufficient?
|
||||
|
||||
## 6. Merge
|
||||
|
||||
Before merge:
|
||||
|
||||
- Required checks pass.
|
||||
- Review comments are resolved.
|
||||
- Branch is up to date according to project policy.
|
||||
- Release notes or changelog entries are added when relevant.
|
||||
|
||||
## 7. Release
|
||||
|
||||
Follow [release-process.md](release-process.md).
|
||||
|
||||
Release work should include:
|
||||
|
||||
- Final readiness check.
|
||||
- Deployment.
|
||||
- Smoke test.
|
||||
- Monitoring.
|
||||
- Rollback readiness.
|
||||
|
||||
## 8. Review Outcome
|
||||
|
||||
After meaningful releases or incidents:
|
||||
|
||||
- Capture what worked.
|
||||
- Capture what failed.
|
||||
- Update checklists, docs, tests, or runbooks.
|
||||
- Add ADRs for decisions that emerged during delivery.
|
||||
Reference in New Issue
Block a user