Day 3 Mission 01 Decision logging

Mission 01. Design Decision Log

Automatically write a standard Design Decision Log (Why) report recording database normalization and architecture decisions.

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

  1. Create the lab file: press the download button below and save tech-design-meeting.md in the automation/ folder.
  2. Hand logging to Codex: send the **Codex request prompt** below in the Codex Client prompt box and build.
  3. 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 ID: DEC-003]
• 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.