How a Wise Developer Works on a New Project

A wise developer does not “start coding and hope.” They move a new project through brainstorming, teammate discussion, prototyping, diagrams, proposals, ADRs, MRs/PRs, and GitOps — with Review Bots auto-generating PR comments so humans spend time on what matters. This is the production-grade playbook. An FDE can stand the system up; Claude Architect Certification is worth pursuing if you want to design and defend it.

1. What “wise” means on a new project

Wisdom is not more meetings. It is cheap learning early and expensive mistakes late made rare. The sequence below is ordered so each step reduces the blast radius of the next:

Brainstorm → Discuss → Prototype → Diagram → Propose → ADR
        → Implement in small slices → MR/PR + Review Bot → Merge
        → GitOps promote (dev → staging → prod) → Observe → Iterate

Skip steps only with intent (e.g. a one-line config fix). Never skip Review Bot + CI on anything that can reach production.

2. Brainstorming (solo first, then structured)

Before you ask anyone for time, spend 30–90 minutes alone:

• Outcome: what user/business change must be true when we are done?
• Constraints: time, budget, compliance, existing platforms, skills on the team.
• Non-goals: what we will not build in v1 (protects scope).
• Risks: data, security, performance, vendor lock-in, operational load.
• Success metrics: latency, error rate, adoption, cost — pick two that matter.

Capture this in a short note (Notion/Confluence/markdown in the repo under docs/ideas/). Brainstorming without a written artifact is just conversation that evaporates.

3. Discussions with workmates

Invite the smallest useful circle: one peer who will implement with you, one person who owns the adjacent system, and (when needed) security or SRE. Rules that keep it wise:

• Time-box (25–45 minutes). End with decisions or open questions — not vibes.
• Disagree on options, not people. Force “option A vs B vs defer.”
• Assign a scribe. The note becomes the seed of the proposal.
• No silent vetoes. If someone is uncomfortable, write the concern as a risk in the ADR later.

Async works too: a short RFC comment thread often beats a meeting — but someone must still close the loop.

4. Prototyping (spikes with an expiry date)

Prototype when uncertainty is high: a new API, an unfamiliar cloud service, a performance question, or AI/agent behaviour. Wise rules:

1. Name it a spike in the ticket; set a calendar stop (1–3 days typical).
2. Keep code on a throwaway branch or spikes/ folder; do not polish.
3. Write down what you learned in 10 bullets — especially what failed.
4. Decide: promote (refactor into product), rewrite, or abandon.

Prototypes that quietly become production without an ADR are how teams inherit accidental architecture.

5. Diagrams (enough to argue about)

You do not need a UML novel. Prefer three sketches that fit on one screen each:

Diagram	Answers
Context (C4 L1)	Who talks to what? Trust boundaries?
Sequence	Happy path + one failure path
Deployment	Where it runs; how config and secrets flow

Store Mermaid or images next to the proposal (docs/architecture/). Update diagrams when ADRs change — stale pictures are worse than none.

6. Proposals (lightweight RFC)

A good proposal is one to three pages:

1. Problem and why now
2. Options considered (at least two)
3. Recommendation and why
4. Impact: security, cost, ops, migration
5. Rollout and rollback
6. Open questions

Ask for review with a clear deadline. When approved (or approved with amendments), turn the decision into an ADR — do not leave the “source of truth” in chat.

7. ADR — Architecture Decision Records

An ADR is a short, immutable-by-convention record of a decision. Template:

# ADR-00XX: Title

Status: Proposed | Accepted | Superseded by ADR-00YY
Date: YYYY-MM-DD
Deciders: @alice @bob

## Context
What forces are in play?

## Decision
What we will do.

## Consequences
Positive, negative, and follow-ups.

## Alternatives considered
Option A — why not
Option B — why not

Keep ADRs in git (docs/adr/). Link them from PRs. Supersede rather than rewrite history — future you needs the trail.

8. MR and PR — the unit of delivery

MR (Merge Request, GitLab) and PR (Pull Request, GitHub/Bitbucket) are the same idea: a reviewable change set. Wise habits:

• Small: ideally <400 lines of meaningful diff; split vertical slices.
• One intent: one feature, fix, or chore — not “misc.”
• Description: why, how to test, screenshots/logs, risk, rollback.
• Links: ticket + ADR + design diagram.
• Draft first when you want early feedback without implying “ready to merge.”
• Never force-merge around red CI or unresolved high-severity bot findings without written exception.

Example PR body checklist

## Summary
- …

## Test plan
- [ ] Unit tests
- [ ] Manual path …
- [ ] Feature flag / config …

## Risk & rollback
- Risk: …
- Rollback: revert this PR / GitOps revert commit …

## References
- ADR-00XX
- Ticket ABC-123

9. Review Bot usage — auto-generated PR comments

A Review Bot is an automated reviewer that posts inline comments and summaries on every MR/PR. It does not replace humans; it front-loads the boring and the dangerous.

9.1 What the bot should comment on

• Security: injection, authz gaps, secret leakage, insecure defaults
• Correctness: null paths, race conditions, broken migrations
• Tests: missing coverage on new branches, snapshot abuse
• API/contract: breaking changes without version bump
• Ops: missing timeouts, no idempotency, unbounded retries
• Style only when it escaped formatter/linter (avoid noise)

9.2 How it streamlines developer life

1. Author opens PR → bot runs in seconds to minutes.
2. Author fixes or replies to bot threads before asking humans.
3. Human reviewer reads bot summary + focuses on design and product risk.
4. Fewer “nit” rounds; faster merge; fewer Friday-night incidents from missed footguns.

9.3 Typical setup options

Approach	Notes
SaaS Review Bot (e.g. CodeRabbit, vendor bots)	Fast to enable; tune severity and path filters
Cursor Bugbot / IDE-linked review	Strong on PR diffs in Cursor-centric teams
Custom GitHub Action + Claude / LLM	Full control; needs prompt + policy + cost caps
Layered pipeline (lint → SAST → LLM)	Best production posture — see AI code review pipeline guide

9.4 Policy that keeps the bot useful

• Severity labels: blocker / should-fix / nit — nits must not block merge.
• Ignore generated paths (vendor/, lockfiles noise, protobuf dumps).
• Require human approval for security-sensitive paths (auth/, infra/, IAM).
• Log false positives; feed them back into ignore rules monthly.
• Never let the bot be the only reviewer on production-critical services.

9.5 Minimal GitHub Action sketch

# .github/workflows/review-bot.yml
name: review-bot
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Run Review Bot
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: |
          # Fetch diff, call your review CLI, post review comments via gh api
          ./scripts/review-bot.sh

Implement review-bot.sh to: compute the PR diff, call your model with a strict system prompt (security + correctness first), and post comments with the GitHub/GitLab API. Cap tokens and skip drafts if cost is a concern.

10. GitOps best practices for production-grade quality

GitOps means: 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 folders: apps/ vs envs/dev|staging|prod).
• No kubectl apply to prod as the happy path — break-glass only, audited.
• Progressive delivery: auto-sync dev; manual or gated sync for prod.
• Image digests over mutable tags in prod manifests.
• Policy as code: OPA/Kyverno for privilege, registries, resource limits.
• Signed commits / provenance where your threat model requires it.
• Observe after sync: health checks, error budgets, automatic rollback hooks when ready.

Code quality is not only “clean functions.” It is also how change enters production. GitOps makes that path reviewable, reversible, and repeatable.

11. End-to-end quality gates (optimised for production)

Local:     pre-commit (fmt, lint, secrets) + unit tests
PR open:   CI (build, test, SAST) + Review Bot comments
PR merge:  human approve + branch protection + required checks
Main:      build immutable artifact (image digest)
GitOps:    update env repo / overlay → sync → verify
Prod:      SLOs + alerts + runbook linked from ADR/PR

12. FDE role — who sets this system up

A Forward Deployed Engineer is ideal to install the wise-developer system inside a real team:

• Repo templates: docs/adr/, PR template, CODEOWNERS, branch protection
• Review Bot + secrets + cost controls
• CI required checks and environment protections
• GitOps apps (dev/staging/prod) and promotion docs
• Two-week coaching: first ADR, first bot-tuned PR, first GitOps rollback drill

Indicative calendar for an FDE-led enablement on one product repo: 1–2 weeks for scaffolding and bot policy; +1–2 weeks for GitOps promotion path and a dry-run rollback. Culture change takes longer — measure merge time and escaped defects, not tool installs.

13. Claude Architect Certification — worth pursuing

If you design systems where humans and AI agents co-author code, Claude Architect Certification is worth pursuing. It signals that you can:

• Architect AI-assisted delivery without treating the model as infallible
• Specify review policies, guardrails, and evaluation for agentic workflows
• Communicate trade-offs (latency, cost, privacy, accuracy) to stakeholders
• Coach teams on ADRs, PR discipline, and production gates alongside AI tools

Pair the credential with real delivery: stand up a Review Bot, write three ADRs, and run a GitOps rollback drill. Paper without practice does not make you wise; practice plus a shared language does.

14. Anti-patterns (what unwise looks like)

• Giant PR with “WIP please approve ASAP”
• Architecture decided only in Slack, never in ADR
• Prototype merged as prod with no tests
• Disabling Review Bot because “it nags”
• Hotfix to prod outside GitOps with no revert plan
• Humans repeating formatter nits the bot already caught

15. Copy-paste starter checklist for a new project

1. Create docs/ideas/, docs/architecture/, docs/adr/
2. Add PR/MR template + CODEOWNERS
3. Enable pre-commit + CI required checks
4. Install Review Bot; tune path filters and severities
5. Write ADR-0001: “We use GitOps for deploy”
6. Define environments and promotion rules
7. Schedule a 30-minute rollback game day
8. Book FDE time for first-month coaching; consider Claude Architect Certification for leads

16. 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. That is how code quality is optimised for production grade without burning the team on endless nitpicks. Let an FDE install the rails; let certified architects keep the system honest as AI accelerates how fast you can write code.

Published by Workstation.