Customer Communication for Contracting Developers
Applies to: every engineer who delivers software to a customer as a contractor · Time to learn: 30 min reading + 15 min to set up your templates
As a contracting developer you are the customer's most frequent view of the project. They rarely read your code; they read your messages, attend your demos, and judge the work by how clearly you describe it. Good communication is polite, precise, and concrete about the technical project: what is done, what is next, what is at risk, and what you need from them.
- Be polite, precise, and concrete. Every message answers: what is done, what is next, what is blocked, what is at risk, what decision is needed.
- Use dates, numbers, and names instead of adjectives. "3 of 5 endpoints merged; remaining 2 by Thursday 14:00" beats "almost done".
- Write down everything agreed verbally, the same day, and ask for a reply if anything is wrong.
- Deliver bad news early, with the facts, the impact, and two or three options.
- On technical disagreements, explain the trade-offs and record the decision. The customer decides business priorities; you make sure the decision is informed.
- Agree channels and response times at kickoff. Never discuss other customers.
Why it matters
A contract defines what you deliver (see Contracts, Scope, and Boundaries). Communication is how the customer experiences that delivery day to day. Three things follow from that:
- Transparency builds trust. The Scrum Guide puts it this way: "Transparency enables inspection. Inspection without transparency is misleading and wasteful." A customer who can see the work can steer it.
- Written precision prevents disputes. Most scope arguments start as two people remembering a conversation differently.
- Early signals preserve options. A slip reported three weeks ahead has several fixes. The same slip reported the day before has one.
Ownership of what you deliver, including work produced with coding agents, is covered in Accountability. This page covers how you talk about it.
Know your stakeholders
Name the people on the customer side in the first week and write down what each one needs. One person can hold several roles.
| Role | What they care about | What they need from you | Typical channel |
|---|---|---|---|
| Sponsor (pays, owns the budget) | Business outcome, budget, timeline, risk | One-page status with dates, spend vs. plan, risks, and decisions needed | Weekly written status, milestone demos |
| Product owner (owns priorities) | Scope, priority order, trade-offs | Clear options with effort and impact; early notice when scope and capacity diverge | Planning calls, backlog, demos |
| Technical counterpart (architect, lead, ops) | Fit with their systems, security, maintainability | Design notes, interface details, access requests, honest technical risk | Chat, pull requests, design reviews |
| End users | Whether the tool helps them do their job | Demos in their language, a way to give feedback, release notes in plain words | Demos, feedback sessions, release notes |
Practical consequences:
- Send the same facts to everyone but shape the framing to the reader: dates and risk for the sponsor, trade-offs for the product owner, interfaces and constraints for the technical counterpart, tasks and benefits for end users.
- Ask in week one: who approves scope changes, who accepts deliverables, who can I ask for access? Put the answers in the project README or kickoff notes.
- Do not route decisions around the owner of that decision. If a technical lead asks for a change that affects scope, bring the product owner in.
Communication cadence
Agree the rhythm at kickoff and keep it even when there is little news. A short "no change, on track" message is also information.
| Moment | Format | Content | Owner |
|---|---|---|---|
| Kickoff | Meeting + written recap | Goals, success criteria, roles, channels, response times, cadence, working hours, access list, first milestone | You and the product owner |
| Weekly status | Written, same day and time each week | Done / next / blocked / risks / decisions needed (template below) | You |
| Demo | Live, working software | What changed since the last demo, what feedback you need, what is next. The Scrum Guide describes the Sprint Review as the moment where the team "presents the results of their work to key stakeholders" and progress is discussed; use the same idea even if you do not run Scrum | You |
| Written recap | Email or ticket comment within 24 hours of any meeting | Decisions, actions with owners and dates, open questions | You |
| Milestone or handover | Report + walkthrough | Results against the agreed criteria, open items, next steps | You |
Write a status update
A status update has one job: let a busy reader decide in two minutes whether they need to act. Keep the structure fixed so readers learn where to look. Use dates and numbers; link to the evidence (board, pull requests, test report).
Subject: [Project] Status week 43 – on track / at risk / blocked
Summary (1–2 sentences)
We merged 3 of 5 planned endpoints; the remaining 2 are on track for Thursday 14:00.
Done since last update
- Orders API: GET /orders and POST /orders merged, 42 of 42 tests passing (link)
- Staging deployed, version 0.3.1 (link)
Next (until next update)
- Remaining 2 endpoints by Thu 14:00
- Demo to key users on Fri 10:00
Blocked / waiting on you
- Test credentials for the payment sandbox, requested 14 Oct. Needed by Wed 12:00
to keep the Friday demo.
Risks
- Payment sandbox rate limit (10 requests/min) may slow load testing.
Impact: load test results 1 day later. Mitigation: run against a mock first.
Decisions needed
- Pagination style: cursor (recommended, stable under writes) or offset (simpler).
Decision needed by Wed 17:00; default if no reply: cursor.
Numbers
- Budget: 14 of 40 days used (35 %), plan at this point: 15 days
- Open defects: 2 minor, 0 blocking
Rules that keep the update useful:
- Lead with the state (on track, at risk, blocked) and the reason in one sentence.
- Every blocker names a person, a date, and the consequence of missing it.
- Every decision request has options, a recommendation, a deadline, and a default.
- Report against the plan. Compare to the dates and numbers agreed earlier, not to your own feelings.
- Keep it short. If the update needs a page, attach the detail and keep the body on one screen.
Precise language beats vague language
Vague words feel safe, but they make the reader guess, and guesses turn into expectations. Replace them with something the reader can check.
| Vague | Concrete rewrite |
|---|---|
| "Almost done" | "3 of 5 endpoints merged; remaining 2 by Thursday 14:00" |
| "It should work now" | "Fixed in commit a1b2c3d; reproduced on staging before and after; regression test added" |
| "We're making good progress" | "12 of 20 stories done; velocity matches plan; one risk below" |
| "Soon" / "ASAP" | "Tomorrow, Wednesday 16:00" |
| "A few small issues" | "2 open defects: login timeout (minor), CSV export encoding (minor); both scheduled for Friday" |
| "The system is slow" | "p95 response time is 2.8 s on the search endpoint; target is 1.5 s" |
| "We'll look into it" | "I will have a root cause by Tuesday 12:00 and send you the finding" |
| "It's a big change" | "About 6 days including tests; touches the billing and reporting modules" |
| "Can't do that" | "That needs 8 more days. Options: drop feature X (0 days), or move the deadline to 14 Nov" |
| "The customer's API is broken" | "The orders endpoint returns HTTP 500 for 3 of 20 test requests (log attached). Can your team look at it by Wednesday?" |
| "Testing is fine" | "Unit tests: 184 passed, 0 failed. Integration tests: 31 passed, 1 skipped (needs sandbox credentials)" |
How to apply it:
- Say what you know, what you assume, and what you do not know yet. "Confirmed: the bug is in the import job. Assumed: only files over 10 MB are affected. Unknown: since which release."
- Attach a date to every promise and meet it, or report the miss before it happens.
- Give estimates as ranges with assumptions: "5 to 8 days, assuming the schema does not change."
- Write for the reader's knowledge level. Use the customer's domain words; explain technical terms once.
- Be polite by default: greet, say please and thank you, acknowledge the question before answering it, and keep the focus on the problem, not the person.
Confirm everything agreed in writing
Verbal agreements are fine for speed, and unreliable as records. After every meeting or call that decides something, send a recap within 24 hours. State that you will treat it as agreed unless someone corrects it by a given date.
Subject: Recap: [Project] [topic], [date]
Hi all, thanks for the time today. Here is what I understood. Please reply by
[date] if anything is wrong or missing.
Attendees: [names]
Decisions
1. Reporting export ships as CSV in release 1, Excel in a later release. (product owner)
2. Authentication uses the customer's existing SSO. (customer IT)
Actions
| Action | Owner | Due |
|---|---|---|
| Provide SSO test tenant | Customer IT lead | Wed 22 Oct |
| Send revised wireframes | Product owner | Fri 24 Oct |
| Update estimate for SSO integration | Me | Mon 27 Oct |
Open questions
- Who approves production access? Needed by 3 Nov.
Impact on plan
- No change to the 14 Nov milestone, assuming the SSO tenant arrives on time.
Next meeting: Thu 30 Oct, 10:00.
Why it works:
- It turns memory into a record both sides can point to.
- It exposes misunderstandings while they are cheap to fix.
- It gives you the paper trail for scope questions; how to handle those formally is in Contracts, Scope, and Boundaries.
If a decision arrives in chat or a hallway conversation, write one line back: "Confirming: we use SSO, not local accounts. This keeps the estimate as is. Shout if I got that wrong."
Deliver bad news early, with options
Problems do not improve with age. The moment you see a risk that threatens a date, a budget, or a quality bar, tell the right person.
Structure the message in this order:
- Fact: what happened or what you found, with numbers.
- Impact: what it means for dates, cost, scope, or quality.
- Cause: what you know now, and what you will know by when.
- Options: two or three, each with effort, trade-off, and your recommendation.
- Ask: the decision you need and the deadline.
Subject: Heads-up: [Project] reporting module may slip by 3 days
Fact: The legacy data export returns inconsistent dates for 8 % of rows
(412 of 5,150 in the sample, attached).
Impact: Normalising them adds about 3 days. The 14 Nov milestone moves to 19 Nov
unless we change scope.
Cause: Two date formats in the source system. Confirmed by Tuesday with a full-file scan.
Options:
A. Normalise in the import (3 days, recommended, fixes it for all reports)
B. Ship with the 8 % flagged for manual review (0 days, needs a process on your side)
C. Ask your team to clean the source data (effort on your side, unknown duration)
Ask: Please choose by Thursday 12:00 so I can keep the milestone for the other
modules.
Tips:
- Tell the product owner or sponsor directly, then recap in writing. Do not let them learn it from a demo.
- Own your part without drama. Stay factual, say what you will do differently, and skip both excuses and self-blame. The Google SRE book makes the same point for incidents: a blameless approach focuses on contributing causes "without indicting any individual or team," so people raise problems early.
- Never bury the news in the middle of a long update. Put it in the subject line.
- Related: how to set expectations at the start of a proof of concept is in PoC Expectations → MVP.
Stay polite under pressure
Pressure shows up as urgent messages, shifting priorities, and sharp tone. The goal is to keep the conversation on facts and next steps.
| Situation | What to do |
|---|---|
| Escalated or angry message | Wait before you reply. Acknowledge the concern in one sentence, restate the facts, offer a next step with a time. Move to a call if text is escalating, then send a recap |
| "Why is this late?" | Give the plan, the actual, the cause, and the recovery options. Do not defend; explain |
| Request that sounds like a scope change | "Happy to do this. It is outside the current scope, so here is the effort and what it displaces. Do you want it in this release?" See Contracts, Scope, and Boundaries |
| Unclear or contradictory requests | Ask one clarifying question with an example, then restate your understanding in writing |
| Silence on a blocker | Follow up once with the date and impact, then involve the person who owns the priority |
| Criticism of your work | Thank them, reproduce the issue, give a fix date. Fix first, discuss cause afterwards |
Useful phrases that stay polite and stay precise:
- "Let me check and come back to you by 15:00 today."
- "I understand the deadline matters. Here is what I can commit to and what I cannot."
- "To make sure I have this right: you want A before B. Correct?"
- "I do not know yet. I will know after the load test on Tuesday."
Disagree on technical decisions
You were hired for your technical judgement, so use it openly. The customer owns business priorities; you own giving them an informed picture.
- State the goal you both share. "We both want a reporting module that stays fast with 10x data."
- Lay out the options and trade-offs with cost, risk, and maintenance impact. A small table works well.
- Give a recommendation and your reasoning. One recommendation, not a menu of equal options.
- Let the decision owner decide. If the customer chooses differently on business grounds (deadline, budget, strategy), respect it and deliver it well.
- Document the decision. Date, options considered, who decided, and the known consequences, in a short decision record in the repository or the project wiki.
- Raise it again only with new facts, such as a measurement or a changed requirement.
# 0007 Pagination style for the orders API
- Date: 2026-10-22
- Decided by: product owner, advised by the contracting team
- Options: cursor-based (recommended), offset-based
- Decision: offset-based, to match the customer's other APIs
- Consequences: results can shift under concurrent writes; the contracting team
flagged this risk on 2026-10-21; revisit if the table exceeds 1 M rows
When a decision touches security, data protection, or legal compliance, say clearly that the risk is yours to report, not to accept on the customer's behalf. Escalate through the agreed channel and keep the record.
The same applies when coding agents helped produce the work: you present it, you stand behind it, and you describe it accurately (see Accountability and How We Build).
Channels and response times
Agree these at kickoff and write them in the recap.
| Topic | Agree on |
|---|---|
| Channels | One for day-to-day questions (chat), one for decisions and records (email or tickets), one for code (pull requests). Decisions made in chat get a one-line written confirmation |
| Response times | For example: acknowledge within 1 working day, answer routine questions within 2 working days, urgent production issues through an agreed escalation contact. Choose values that fit the engagement and write them down |
| Working hours and time zones | Core overlap hours, holidays, planned absences, and who covers you |
| Escalation path | Who to contact when the usual person is unreachable, and for which severity |
| Who may ask for what | Who can request changes, who accepts work, who grants access |
Keep your side of it: acknowledge messages even when the answer takes longer ("Received. Answer by Wednesday noon."). Announce absences in advance.
Confidentiality and other customers
- Do not mention other customers, their projects, their problems, or their people, not even anonymised in a way someone could guess. If you reuse a general technique, describe the technique only.
- Treat what you learn as confidential: data, architecture, plans, internal conversations, and credentials. Follow the confidentiality terms in your contract and the customer's security rules.
- Keep customer data out of the wrong places: personal chat apps, public issue trackers, public AI tools, and screenshots in shared channels. Check the customer's approved tools before you use them (see AI-Native Engineering on harness choice and data rules).
- Share lessons without identifiers. Internal write-ups should follow the same privacy-conscious practice the SRE book describes for postmortems, which never include information that could identify an end user.
- Ask before you publish anything about the project, such as a talk, a blog post, or a portfolio entry.
Pitfalls to design around
- Updates that depend on memory → keep the template in a snippet, send it on the same day each week, and fill it from the board and pull requests.
- Adjectives instead of evidence → replace every "good", "soon", and "almost" with a number, date, or link before you hit send.
- Verbal agreements that fade → send the recap within 24 hours; one line is enough.
- Bad news that waits for the next status call → send it when you find it, with options, and discuss it live afterwards.
- Technical disagreements that become personal → return to the shared goal and the trade-off table, and record the outcome.
- One message for all audiences → keep the facts identical and adapt the framing and the length per stakeholder.
- Silent blockers → state who, what, by when, and the consequence; follow up once, then escalate through the agreed path.
- Unclear channels → write the channels and response times into the kickoff recap so nobody has to guess.
- Overpromising to please → commit to what you can verify, and offer a date for the rest.
Communication checklist per engagement
- Stakeholders listed (sponsor, product owner, technical counterpart, end users) with roles and decision rights
- Kickoff held and recap sent, including goals, success criteria, and first milestone
- Channels, response times, working hours, and escalation path agreed in writing
- Weekly status sent on the agreed day, using done / next / blocked / risks / decisions needed
- Every blocker has an owner, a date, and a stated consequence
- Demos scheduled at a regular interval, with feedback captured
- Every meeting followed by a recap within 24 hours
- Risks reported when found, with options and a recommendation
- Technical decisions recorded with date, options, and decision owner
- Scope-affecting requests answered with effort and trade-off (see Contracts, Scope, and Boundaries)
- No other customers mentioned; customer data handled only in approved tools
- Handover message sent with results against criteria and open items
Sources
- Schwaber and Sutherland — The Scrum Guide (Sprint Review: the team "presents the results of their work to key stakeholders"; "Transparency enables inspection. Inspection without transparency is misleading and wasteful.")
- Beck et al. — Manifesto for Agile Software Development ("Customer collaboration over contract negotiation")
- Google — Site Reliability Engineering, Postmortem Culture: Learning from Failure (blameless focus on contributing causes "without indicting any individual or team"; postmortems exclude information that could identify an end user)