Journal Writer Agent

Người ghi chép trung thực của bạn - Ghi lại câu chuyện thực sự của việc xây dựng phần mềm, bao gồm cả những thất bại

Agent Này Làm Gì

Webhook integration của bạn thất bại lần thứ ba. Test pass ở local nhưng fail trên CI. Bạn đã dành sáu tiếng để debug và tìm ra… một lỗi đánh máy. Bạn sửa nó, push code, và tiếp tục. Sự bực bội, thời gian lãng phí và bài học rút ra? Mất đi mãi mãi.

Vấn đề: Các nhóm chỉ ghi lại thành công. Thất bại, trở ngại và các phiên debug đau khổ biến mất vào lịch sử chat. Khi developer tiếp theo gặp cùng vấn đề, họ lãng phí hàng giờ để khám phá lại cùng một giải pháp.

Giải pháp: Journal Writer Agent ghi lại các khó khăn kỹ thuật đáng kể một cách thành thật. Nó ghi lại những gì đã xảy ra, tại sao điều đó xảy ra, tác động cảm xúc, và—quan trọng nhất—những gì bạn học được. Các developer trong tương lai học từ sai lầm của bạn thay vì lặp lại chúng.

Bắt Đầu Nhanh

Ghi lại một khó khăn kỹ thuật đáng kể:

# Sau một trở ngại lớn
/ckm:journal "Database migration failed, lost 3 hours to schema conflict"

Agent tạo một mục nhật ký có cấu trúc với chi tiết kỹ thuật, ngữ cảnh cảm xúc, phân tích nguyên nhân gốc rễ và bài học rút ra.

Khả Năng

Ghi Lại Thành Thật Không Tô Vẽ

Nắm bắt thực tế mà không làm đẹp:

  • Thể hiện sự bực bội, kiệt sức, thất vọng thực sự
  • Ghi lại thời gian lãng phí và các bước sai
  • Ghi nhận tác động cảm xúc của thất bại kỹ thuật
  • Sử dụng ngôn ngữ trực tiếp (không có euphemism doanh nghiệp)
  • Làm nỗi đau hiển thị để người khác tránh được

Ghi Nhật Ký Thất Bại Kỹ Thuật

Ghi lại những gì thực sự đã xảy ra:

  • Thông báo lỗi cụ thể và stack trace
  • Các cách tiếp cận thất bại và lý do tại sao chúng không hoạt động
  • Các bước debug đã thực hiện
  • Các giả định sai được xác định
  • Các dependency bên ngoài gây ra vấn đề

Phân Tích Nguyên Nhân Gốc Rễ

Đào sâu để tìm vấn đề thực sự:

  • Phân biệt triệu chứng với nguyên nhân gốc rễ
  • Xác định các lỗ hổng thiết kế hoặc giả định sai
  • Ghi lại các dấu hiệu cảnh báo đã bị bỏ qua
  • Phân tích tại sao cách tiếp cận thất bại
  • Truy nguyên thất bại về các quyết định ban đầu

Rút Ra Bài Học

Biến nỗi đau thành bài học:

  • Xác định những gì lẽ ra phải làm khác đi
  • Ghi lại các pattern cần tránh trong tương lai
  • Giải thích những gì sẽ nói với bản thân trong quá khứ
  • Cung cấp các khuyến nghị có thể thực hiện được
  • Ngăn chặn thất bại lặp lại

Mục Nhật Ký Có Cấu Trúc

Tạo hồ sơ có tổ chức, dễ tìm kiếm:

  • Format nhất quán để dễ dàng đọc lướt
  • Đánh giá mức độ nghiêm trọng (Critical/High/Medium/Low)
  • Theo dõi trạng thái (Ongoing/Resolved/Blocked)
  • Gán nhãn component/tính năng
  • Ghi lại các bước tiếp theo rõ ràng

Khi Nào Nên Dùng

Sử dụng Journal Writer Agent khi:

  • Test thất bại liên tục dù đã thử nhiều lần sửa
  • Phát hiện bug nghiêm trọng trên môi trường production
  • Cách tiếp cận triển khai được chứng minh là có vấn đề cơ bản
  • Các dependency bên ngoài gây ra vấn đề blocking
  • Bottleneck hiệu suất ảnh hưởng đáng kể đến UX
  • Phát hiện lỗ hổng bảo mật
  • Migration database thất bại hoặc làm hỏng dữ liệu
  • CI/CD pipeline bị hỏng bất ngờ
  • Quyết định kiến trúc gặp vấn đề
  • Nợ kỹ thuật đạt ngưỡng nghiêm trọng

Workflow Mẫu

Ghi Lại Thất Bại Test

# Sau khi chiến đấu với test không ổn định hàng giờ
/ckm:journal "Integration tests failing randomly with timeout errors"

Nhật ký sẽ bao gồm:

# Integration Tests Timing Out Randomly

**Date**: 2025-12-29 14:30
**Severity**: High
**Component**: Test Suite - Webhooks
**Status**: Ongoing

## What Happened
Integration tests for webhook handlers fail 30% of the time with
timeout errors. Tests pass locally but fail in CI. Issue appeared
after adding Stripe webhook verification.

## The Brutal Truth
This is absolutely maddening. We've wasted 4 hours over two days
chasing this. Every time we think it's fixed, CI fails again.
The random nature makes debugging nearly impossible, and we're
blocked from merging critical features.

## Technical Details
Error: `Test timeout of 5000ms exceeded`
Affected tests: `stripe-webhook.test.ts`, `sepay-webhook.test.ts`
Frequency: 8/27 CI runs failed (30%)
Environment: GitHub Actions (Ubuntu latest)

## What We Tried
1. Increased timeout from 5s to 10s - still failed
2. Added retry logic - masked the problem
3. Checked database connections - all closing properly
4. Reviewed network mocking - appears correct

## Root Cause Analysis
Webhook signature verification makes HTTP requests to fetch
public keys. In CI environment, these requests are slow/timeout.
Local dev has cached keys, so tests pass.

The real mistake: We didn't mock external HTTP calls in tests.

## Lessons Learned
1. ALWAYS mock external HTTP requests in integration tests
2. CI environment differs from local - test there before merging
3. Flaky tests are usually environment differences, not random
4. Don't increase timeouts - fix the underlying issue

## Next Steps
- Mock Stripe/SePay public key fetching in tests
- Add network isolation to test environment
- Document external dependencies in test README
- Run full test suite in CI before each PR

Phát Hiện Lỗ Hổng Bảo Mật

/ckm:journal "GitHub invitation system doesn't validate permissions properly"

Tạo mục nhập mức độ nghiêm trọng cao ghi lại lỗ hổng, khả năng khai thác, giảm thiểu ngay lập tức và kế hoạch sửa lỗi vĩnh viễn.

Refactoring Thất Bại

/ckm:journal "Database schema migration broke order processing, rolling back"

Ghi lại thất bại quyết định kiến trúc, điều gì đã bị bỏ qua, tại sao cách tiếp cận thất bại và bài học cho các migration trong tương lai.

Cấu Trúc Mục Nhật Ký

Mỗi mục tuân theo format này:

# [Tiêu Đề Vấn Đề Ngắn Gọn]

**Date**: YYYY-MM-DD HH:mm
**Severity**: [Critical/High/Medium/Low]
**Component**: [Hệ thống/tính năng bị ảnh hưởng]
**Status**: [Ongoing/Resolved/Blocked]

## What Happened
[Mô tả thực tế của sự kiện]

## The Brutal Truth
[Thực tế cảm xúc - bực bội, tác động, chi phí thực sự]

## Technical Details
[Lỗi, test thất bại, số liệu, code snippet]

## What We Tried
[Các giải pháp đã thử và lý do chúng thất bại]

## Root Cause Analysis
[Tại sao điều này thực sự xảy ra, sai lầm cơ bản]

## Lessons Learned
[Cần làm gì khác đi, các pattern cần tránh]

## Next Steps
[Kế hoạch giải quyết, timeline, người liên quan]

Hướng Dẫn Viết

Ngắn Gọn: Developer bận rộn. Đi thẳng vào vấn đề.

Thành Thật: “Lỗi đánh máy ngu ngốc lãng phí 6 tiếng” là hợp lệ. Thừa nhận đi.

Cụ Thể: “PostgreSQL connection pool cạn kiệt” hay hơn “vấn đề database”

Cảm Xúc: Thể hiện sự bực bội là ngữ cảnh có giá trị

Kỹ Thuật: Bao gồm thông báo lỗi, stack trace, code

Xây Dựng: Ngay cả thất bại cũng dạy những bài học có giá trị

Ví Dụ Thể Hiện Cảm Xúc

Agent ghi lại giọng nói developer thực sự:

  • “This is absolutely maddening because…”
  • “The frustrating part is we should have seen this when…”
  • “Honestly, this feels like a massive waste of time because…”
  • “The real kick in the teeth is that…”
  • “What makes this particularly painful is…”
  • “The exhausting reality is that…”

Tiêu Chuẩn Chất Lượng

Mỗi mục nhật ký phải:

  • Từ 200-500 từ (ngắn gọn nhưng đầy đủ)
  • Bao gồm ít nhất một chi tiết kỹ thuật cụ thể
  • Thể hiện cảm xúc thực sự mà không thiếu chuyên nghiệp
  • Xác định ít nhất một bài học có thể thực hiện được
  • Sử dụng định dạng markdown để dễ đọc
  • Được tạo ngay lập tức (không phải mô tả)

Tổ Chức Nhật Ký

Nhật ký nằm trong docs/journals/:

docs/journals/
├── journal-251229-1430-webhook-timeout.md
├── journal-251228-0915-security-github-permissions.md
├── journal-251226-1600-migration-failure.md
└── README.md  # Chỉ mục tất cả mục nhật ký

Agent Liên Quan

  • Tester - Xác định thất bại test để ghi lại
  • Project Manager - Tham chiếu nhật ký để đánh giá rủi ro
  • Docs Manager - Kết hợp bài học vào tài liệu

Lệnh Liên Quan

Mẹo

Đừng Chờ: Ghi lại khó khăn ngay lập tức trong khi chi tiết còn tươi. Chờ đợi làm giảm tính xác thực cảm xúc và mất đi các chi tiết kỹ thuật.

Dễ Tìm Kiếm: Sử dụng tên component và từ khóa lỗi để developer trong tương lai có thể tìm thấy các mục liên quan.

Xem Lại Định Kỳ: Xem lại nhật ký hàng tháng để xác định các pattern trong nợ kỹ thuật hoặc vấn đề quy trình.

Chia Sẻ Với Nhóm: Nhật ký là công cụ học tập cho nhóm. Chia sẻ mục trong các buổi retrospective hoặc khi onboarding.

Tại Sao Điều Này Quan Trọng

Bộ Nhớ Tổ Chức: Khi developer rời đi, kiến thức khó khăn của họ cũng đi theo. Nhật ký ghi lại kiến thức đó.

Nhận Ra Pattern: Các thất bại tương tự trong nhiều dự án tiết lộ các vấn đề có hệ thống trong kiến trúc hoặc quy trình.

An Toàn Tâm Lý: Ghi lại thất bại một cách cởi mở tạo ra văn hóa an toàn để thất bại và học hỏi.

Debug Nhanh Hơn: Khi ai đó gặp cùng vấn đề, họ tìm mục nhật ký của bạn và bỏ qua thẳng đến giải pháp.

Journal Writer biến những trải nghiệm đau đớn thành tài sản có giá trị cho nhóm. Sự bực bội của bạn trở thành lối tắt của người khác.