Mission 1 Design Decision Record Lab Guide
📥 Lab input
- •
tech-design-meeting.md(meeting transcript)
💾 Lab output
- •
design-decision-log.md(decision record doc)
1. Story and lab background
Time passes, and a new developer joins and wonders while reading the code: "Why did they make a separate history table that accumulates records, instead of just changing the booking status in the main booking table? Adding one column would have been easier."
The reason was a decision a senior engineer and planner made carefully 6 months ago to meet security/audit requirements and speed up daily cancellation statistics. But since no doc recorded it, the new developer changed the design on their own and caused an outage that took down the whole past cancellation statistics dashboard.
In this mission, you'll learn to use Codex to write the reasons behind data normalization and architecture decisions from the technical design stage as a structured Design Decision Log, and safely manage the system's history and design reasons (Why).
2. Learning goals
- Accurately extract normalization and database structure decisions from meeting notes.
- Write down the decision item, background reason, alternatives reviewed, approver and chance of future change.
- Record the history of design decisions (Why) to prevent repeat meetings and mistakes by new team members.
🛠️ Follow-along lab guide
- Create the lab file: press the download button below and save
tech-design-meeting.mdin theautomation/folder. - Hand logging to Codex: send the **Codex request prompt** below in the Codex Client prompt box and build.
- Check the log: review whether the decision ID (DEC-003), background, alternatives reviewed (rejection reasons) and approver are structured correctly.
Download lab materials
Codex request prompt
Mission 01 Prompt
Extract normalization and database structure decisions from the meeting and write a Design Decision Log including the decision item, background reason, alternatives reviewed, approver and chance of future change.
4. Example output
Codex documents the architectural conclusions and the trade-off reasons from the conversation like this.
• Decision: instead of storing cancellation history directly in the Reservations table, design a separate Reservation_Histories table with a 1:N split.
• Reason (Why): booking status changes often, so this avoids Write Lock bottlenecks on the main table and meets the need to trace history by date and counselor.
• Alternative reviewed: add canceled_at and cancel_reason directly to the Reservations table (rejected: can't record multiple cancellations, and the table would grow too big)
• Approved by: PM and Lead Engineer (approver: Dev_Lead)
• Future change: history may move to a NoSQL Document DB if traffic gets very large.