AzuTear
fc5c13a4fd
Adds AGENTS.md, DESIGN.md, and docs/* covering architecture, conventions, decisions, checklists, branching, release process, and prompts. Updates README and workflow-feedback-plan to reflect the decoupled GroupName nomination model. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
125 lines
3.5 KiB
Markdown
125 lines
3.5 KiB
Markdown
# 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, bug, or feedback"]
|
|
Clarify["Clarify scope"]
|
|
Plan["Plan or ADR"]
|
|
Implement["Implement"]
|
|
Validate["Validate"]
|
|
Review["Review"]
|
|
Merge["Merge"]
|
|
Release["Release"]
|
|
Learn["Update docs/checklists"]
|
|
|
|
Idea --> Clarify
|
|
Clarify --> Plan
|
|
Plan --> Implement
|
|
Implement --> Validate
|
|
Validate --> Review
|
|
Review --> Merge
|
|
Merge --> Release
|
|
Release --> Learn
|
|
```
|
|
|
|
## 1. Clarify Scope
|
|
|
|
Before implementation:
|
|
|
|
- restate the objective in engineering terms;
|
|
- identify affected public, admin, backend, database, or deployment surfaces;
|
|
- confirm acceptance criteria and non-goals;
|
|
- identify security, authorization, migration, data-loss, or live-production
|
|
risk;
|
|
- ask concise questions when ambiguity affects important behavior.
|
|
|
|
## 2. Inspect Existing Context
|
|
|
|
Read the relevant source and docs before editing:
|
|
|
|
- [PROJECT.md](PROJECT.md) for runtime and product facts;
|
|
- [ARCHITECTURE.md](ARCHITECTURE.md) for boundaries;
|
|
- [CONVENTIONS.md](CONVENTIONS.md) for coding standards;
|
|
- [DECISIONS.md](DECISIONS.md) for durable trade-offs;
|
|
- [../DESIGN.md](../DESIGN.md) for UI work;
|
|
- feature plans such as [workflow-feedback-plan.md](workflow-feedback-plan.md)
|
|
when the task builds on planned product feedback.
|
|
|
|
## 3. Plan The Change
|
|
|
|
Use a lightweight plan for non-trivial changes. Create or update an ADR when
|
|
the change affects:
|
|
|
|
- architecture style or module boundaries;
|
|
- data ownership or public contracts;
|
|
- authentication, authorization, or security posture;
|
|
- deployment strategy, migrations, or long-term operating cost.
|
|
|
|
## 4. Implement
|
|
|
|
Implementation expectations:
|
|
|
|
- keep changes focused and reviewable;
|
|
- follow existing frontend/backend patterns;
|
|
- split large Vue surfaces into smaller components or composables;
|
|
- keep backend/admin data authoritative for public behavior;
|
|
- avoid unrelated refactors unless needed for the requested change;
|
|
- preserve user changes in a dirty worktree.
|
|
|
|
## 5. Validate
|
|
|
|
Default validation:
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run build
|
|
|
|
cd ..
|
|
dotnet build Backend/Backend.csproj --configuration Release
|
|
git diff --check
|
|
```
|
|
|
|
Add targeted validation by risk:
|
|
|
|
- API checks for backend behavior;
|
|
- authenticated checks for admin/team/permission changes;
|
|
- browser checks for visible UI changes;
|
|
- responsive geometry checks for layout work;
|
|
- database health and migration checks for schema changes;
|
|
- live checks only for release or explicitly live-scoped work.
|
|
|
|
When frontend and backend are both actively used for local verification, keep
|
|
them running as a pair or shut both down together.
|
|
|
|
## 6. Review
|
|
|
|
Review should answer:
|
|
|
|
- Does the change solve the stated problem?
|
|
- Does it preserve backend/admin truth?
|
|
- Is authorization enforced at the trusted boundary?
|
|
- Are migrations and deployment risk understood?
|
|
- Are docs and validation sufficient for the risk?
|
|
|
|
## 7. Merge And Release
|
|
|
|
`main` is the production deployment branch. Pushes to `main` run CI and deploy
|
|
when the workflow conditions match. Follow [release-process.md](release-process.md).
|
|
|
|
## 8. Learn
|
|
|
|
After meaningful releases, regressions, or repeated review feedback:
|
|
|
|
- update docs or checklists;
|
|
- add or update ADRs;
|
|
- add regression coverage when practical;
|
|
- record follow-up work where the repo exposes an operational or test gap.
|