A wise developer does not start a new project by opening a giant pull request. They move through brainstorming, teammate discussion, prototyping, diagrams, proposals, ADRs, MRs/PRs, and GitOps — with a Review Bot on every change — and, when scale demands it, Workstation’s multi-agent architecture to assemble a great development team that ships production-grade work fast.
1. What “wise” means on a new project
Wisdom is cheap learning early and rare expensive mistakes late. The sequence below is ordered so each step shrinks the blast radius of the next:
Brainstorm → Discuss with workmates → Prototype → Diagram → Propose → ADR
→ Implement in small slices → MR/PR + Review Bot → Merge
→ GitOps promote (dev → staging → prod) → Observe → Iterate
Optional scale-up:
Workstation multi-agent crew (Planner / Builders / Reviewers / Ops)
with human gates on risky actions
2. Brainstorming
Before you spend other people’s time, spend 30–90 minutes alone:
- Outcome — what must be true for the business when we are done?
- Constraints — time, compliance, platforms, skills, budget.
- Non-goals — what v1 will explicitly not include.
- Risks — data, security, performance, lock-in, ops load.
- Success metrics — pick two (e.g. latency + adoption, or cost + error rate).
Write it down under docs/ideas/. Unwritten brainstorms evaporate.
3. Discussions with workmates
Invite the smallest useful circle: a peer implementer, an owner of an adjacent system, and security/SRE when the risk warrants it.
- Time-box (25–45 minutes). End with decisions or open questions.
- Force options: A vs B vs defer — not vague agreement.
- Assign a scribe; the note seeds the proposal.
- Capture discomfort as risks for the ADR — no silent vetoes.
Async RFCs are fine if someone closes the loop.
4. Prototyping
Spike when uncertainty is high. Wise rules:
- Label it a spike; set a calendar stop (1–3 days typical).
- Keep it on a throwaway branch or
spikes/— do not polish. - Write ten bullets on what you learned (especially failures).
- Decide: promote, rewrite, or abandon — never “quietly become prod.”
5. Diagrams
Three sketches are usually enough:
| Diagram | Answers |
|---|---|
| Context (C4 L1) | Who talks to what? Trust boundaries? |
| Sequence | Happy path + one failure path |
| Deployment | Where it runs; config and secrets flow |
Store Mermaid or SVG next to the proposal. Update when ADRs change.
6. Proposals
Keep the RFC short (1–3 pages): problem, options (at least two), recommendation, impact (security/cost/ops), rollout and rollback, open questions. When approved, turn the decision into an ADR.
7. ADR — Architecture Decision Records
# ADR-00XX: Title Status: Proposed | Accepted | Superseded by ADR-00YY Date: YYYY-MM-DD Deciders: @alice @bob ## Context ## Decision ## Consequences ## Alternatives considered
Keep ADRs in git (docs/adr/). Link them from PRs. Supersede rather than rewrite history.
8. MR and PR — the unit of delivery
MR (Merge Request) and PR (Pull Request) are the same idea: a reviewable change set.
- Small (prefer <400 lines of meaningful diff); one intent per change.
- Description: why, how to test, risk, rollback.
- Links: ticket + ADR + diagram.
- Draft early for feedback; never force-merge around red CI or high-severity bot findings without a written exception.
## Summary ## Test plan - [ ] Unit / contract tests - [ ] Manual path … ## Risk & rollback ## References (ADR, ticket)
9. Review Bot — auto comments that protect production
A Review Bot is an automated first reviewer. It does not replace humans; it front-loads the boring and the dangerous so developers spend time on design and product risk.
9.1 What it should comment on
- Security: injection, authz gaps, secret leakage, insecure defaults
- Correctness: null paths, races, broken migrations
- Tests: missing coverage on new branches
- API/contracts: breaking changes without version bumps
- Ops: missing timeouts, unbounded retries, non-idempotent writes
9.2 How it streamlines developer life
- Author opens PR → bot comments in minutes.
- Author fixes or replies before asking humans.
- Human reads bot summary + focuses on architecture and blast radius.
- Fewer nit rounds; fewer escaped footguns in production.
9.3 Policy that keeps the bot useful
- Severity: blocker / should-fix / nit — nits must not block merge.
- Ignore generated paths; tune false positives monthly.
- Require human approval on
auth/,infra/, IAM, and money paths. - Never let the bot be the only reviewer on production-critical services.
Wire SaaS bots (e.g. CodeRabbit), Cursor Bugbot, or a custom Action + LLM over the PR diff. Layer lint → SAST → LLM for the strongest posture.
10. GitOps best practices for production-grade quality
Desired state lives in git. A reconciler (Argo CD, Flux, etc.) makes the cluster match. Promotion is a merge; rollback is a revert.
- Separate app code and env config (or clear
envs/dev|staging|prodoverlays). - No ad-hoc
kubectl applyto prod as the happy path — break-glass only, audited. - Progressive delivery: auto-sync lower envs; gated sync for prod.
- Image digests over mutable tags in prod.
- Policy as code (OPA/Kyverno) for privilege and registries.
- Observe after sync; practice the revert.
Code quality is not only clean functions — it is also how change enters production.
11. Workstation multi-agent architecture — building great development teams
A single wise developer still needs leverage. Workstation’s multi-agent architecture (Agentic AI workstation packages, and OpenClaw for Business where you need embodied or specialised agent crews) lets you auto-build a development team around a business brief — not a static org chart.
11.1 The composition loop
- Brief — stakeholder outcome, constraints, SLA.
- Compose — map roles to skills (Planner, Builder, Reviewer, Ops, Compliance).
- Bootstrap — agent runtime + MCP tools + memory + audit trail.
- Execute — agents pull work, implement against Spec/AC, mini-review each step.
- Review-until-clean — Review Bot + reviewer agents + human gates.
- Ship — GitOps promote to the environment that matters.
11.2 Role map (human + agent)
| Role | Agent does | Human still owns |
|---|---|---|
| Planner | Epics, stories, AC from Spec | Priority and scope cuts |
| Builders | Parallel implementation, tests | Domain judgement on hard edges |
| Reviewers | Spec compliance, Review Bot triage | Architecture and product sign-off |
| Ops | GitOps sync, SLO watch, draft rollback | Go-live and incident command |
| HITL gate | Escalate risky writes / spend | Approve or reject |
11.3 Why this builds great teams
- Specialisation — each agent has one job; quality rises when roles do not blur.
- Throughput without chaos — parallel builders behind a single Spec and Review Bot.
- Shared memory of decisions — ADRs + Spec + PR history become the team’s long-term memory.
- Same gates as humans — CI, Review Bot, CODEOWNERS, GitOps — agents do not bypass production discipline.
- Business speed — hours to stand up a capable crew instead of weeks to hire for every spike.
11.4 How it plugs into the wise path
Brainstorm and discuss still happen with humans. Prototypes and diagrams still happen. The multi-agent crew accelerates proposal drafting, ADR scaffolding, implementation slices, Review Bot triage, and GitOps promotion — while humans keep judgement on outcomes and risk. That is the Workstation model: agentic workstations and OpenClaw packages configured for your workflows, not a chat window pretending to be a team.
12. End-to-end quality gates
Local: pre-commit (fmt, lint, secrets) + unit tests PR open: CI + Review Bot comments PR merge: human approve + branch protection + required checks Main: immutable artifact (image digest) GitOps: update env overlay → sync → verify Agents: Planner/Builder/Reviewer/Ops stay inside the same gates Prod: SLOs + alerts + runbook linked from ADR/PR
13. Starter checklist
- Create
docs/ideas/,docs/architecture/,docs/adr/ - Add PR/MR template + CODEOWNERS + branch protection
- Enable pre-commit + CI required checks
- Install Review Bot; tune path filters and severities
- Write ADR-0001: “We use GitOps for deploy”
- Define env promotion rules and a rollback game day
- If scaling delivery: stand up Workstation multi-agent crew (Planner/Builders/Reviewers/Ops) with HITL gates
14. Anti-patterns
- Giant “WIP please approve” PRs
- Architecture only in Slack — never in ADR
- Prototype merged as prod with no tests
- Disabling the Review Bot because it nags
- Agents with write access and no human gate
- Hotfix to prod outside GitOps with no revert plan
15. Closing
A wise developer treats a new project as a sequence of learning artifacts — notes, diagrams, proposals, ADRs — then delivers through small MRs/PRs watched by a Review Bot and promoted by GitOps. Workstation’s multi-agent architecture extends that wisdom into a full development team: specialised agents, shared Spec, human judgement where it matters, and production-grade gates on every path to live. That is how code quality stays optimised for production while the business still moves fast.
Published by Workstation.
