Zhuang's Diary

Best Practice Framework: Idea → Requirements → Design → Tasks → Implementation

1. Idea Phase

• Articulate the core concept - What problem are you solving?
• Define the value proposition - Why does this matter?
• Identify the target outcome - What success looks like
• Consider alternatives - Are there simpler approaches?

2. Requirements Phase

• Functional requirements - What must the system do?
• Non-functional requirements - Performance, security, scalability
• Constraints - Time, resources, existing tech stack
• Acceptance criteria - How do we know it’s done?

3. Design Phase

• Architecture decisions - High-level structure
• Technology choices - Frameworks, libraries, patterns
• Data flow - How information moves through the system
• Interface contracts - APIs, function signatures, data schemas

4. Tasks Phase

• Break down into atomic units - Each task should be independently completable
• Sequence dependencies - What must happen before what
• Identify risks - Where might things go wrong?
• Plan validation - How to test each task

5. Implementation Phase

• Execute in planned order - Follow the task sequence
• Minimal viable code - Only what’s needed for the requirement
• Validate incrementally - Test each piece as you build
• Refactor if needed - Clean up after core functionality works

Why This Prevents Amazon Q Hanging/Inefficiency

The Problem with Skipping Idea Phase:

1
2
3
4
5

❌ "Build me a user system"
→ Amazon Q guesses at requirements
→ Implements generic solution
→ Doesn't match your actual vision
→ Multiple revision cycles

The Power of Starting with Idea:

1
2
3
4
5

✅ "I want users to collaborate on documents in real-time, like Google Docs"
→ Clear idea and vision
→ Specific requirements emerge naturally
→ Design choices become obvious
→ Implementation is focused and efficient

Practical Application Examples

Example 1: E-commerce Feature

Idea: “Customers abandon carts because checkout is too complex”
Requirements: One-click checkout for returning customers
Design: Store payment methods, streamlined UI flow
Tasks: Payment storage, UI simplification, security validation
Implementation: Minimal code for core flow

Example 2: API Optimization

Idea: “Our API is slow because we’re making too many database calls”
Requirements: Reduce response time by 50% without changing API contract
Design: Implement caching layer and query optimization
Tasks: Add Redis, optimize queries, implement cache invalidation
Implementation: Focused changes to bottleneck areas only

Amazon Q Interaction Best Practices

Communicate the Full Journey

1
2
3
4

"IDEA: I want to add real-time notifications to keep users engaged
REQUIREMENTS: Push notifications for comments, mentions, and updates
DESIGN: WebSocket connection with fallback to polling
CONTEXT: @workspace (existing Express.js app with Socket.io already installed)"

Use Progressive Disclosure

1. Start with the idea and get alignment
2. Drill into requirements together
3. Explore design options
4. Plan tasks collaboratively
5. Execute implementation efficiently

Leverage Context Effectively

@workspacefor understanding the bigger picture
@folder for architectural context
@file for implementation details
Share your idea first, then provide relevant context

Red Flags That Indicate Skipped Phases

• Vague requests - “Make it better” (missing idea)
• Feature creep - Requirements keep expanding (unclear idea)
• Over-engineering - Complex solutions for simple problems (poor design)
• Rework cycles - Constant revisions (inadequate planning)

The Compound Benefits

Each phase informs and improves the next:

• Clear idea → More precise requirements
• Precise requirements → Better design choices
• Better design → Cleaner task breakdown
• Clean tasks → Efficient implementation
• Efficient implementation → Less debugging and rework

This approach works for any agentic coding tool, not just Amazon Q. The key is treating the AI as a collaborative partner in the entire creative process, not just a code generator.

Example

requirements.md

Design.md

Task.md

Reference Link ==> https://catalog.workshops.aws/qadvanced/en-US/00-introduction

在大型国际银行的转型中，Core Banking system系统稳定但僵化，移动网银渠道却要求毫秒级响应与全天候在线。

架构设计 - 数据服务层

核心思想​：将散落在各个“烟囱式”系统（银行卡/信用卡支付、风控、保险等）的数据通过技术手段（CDC、日志解析）实时汇聚起来，构建统一、标准的数据模型，并通过 API 的方式透明地提供给前台应用。核心系统停机时，该数据层能提供​“Stand-In”应急服务——支持只读，甚至有限度的暂存式写入。

• 读写分离：读操作快速由数据服务层响应，写操作依赖主系统保障强一致性；
• 容灾能力提升：主系统故障时自动切换至 Stand-In 模式，关键服务仍可继续执行；
• 真正渐进替代：业务逻辑可逐步迁移至服务层，最终实现核心现代化，不需一蹴而就。

主要机制说明：

• 正常模式：
  • 所有读操作由数据服务层提供低延迟响应；
  • 写操作严格通过 Connector 等连接器进入Core Banking system系统，确保主记录一致性；
  • Core Banking system 通过 CDC（如 Debezium）捕获变更并发布至 Kafka，数据服务层实时消费、更新缓存/数据库，最终一致性得以保障。
• 容灾模式：
  • Core Banking system不可用时，API 网关自动切换路由；
  • 写操作由轻量 Stand-In 服务代为接收，校验后写入本地“待处理交易”队列，并立即反馈客户“处理中”状态；
  • 主系统恢复后，后台任务自动逐笔回放交易，完成结算和Core Banking system同步处理。

治理、风险与项目管控：核心现代化控制塔

借鉴 OliverWyman 建议的 Core Modernization Control Tower，可为该架构增设治理层，关键职责包括  ：

• 跨职能治理机制：聚焦业务、运营、技术多方 alignment，确保宏观战略与技术路径一致；
• 风险管理监督：对迁移过程中的操作风险、合规风险、系统风险进行持续审视；
• 迁移节奏策略：统筹“hollow-out”业务削减主机依赖的节奏与业务模块迁移优先级；
• 变更可视化与沟通机制：提供实时反馈与透明度，保障项目顺滑执行。

技术选型与数据架构策略

1. 流式同步与事件驱动

• Debezium + Kafka：主流国际银行采用 Debezium 捕获 DB2 或主机日志，实时推送事件至 Kafka；这已是金融业标准方案  。

  2. 存储平台设计

• Redis 集群：用于缓存极热数据，支撑毫秒级读性能；
• TiDB / OceanBase：支持强一致性的分布式关系型存储；适用全量账户与交易数据场景。

  3. 数据架构策略

• 结合 Data Mesh / Lakehouse 架构思路提升分析与共享能力；
• 服务层接口应遵循 BIAN / Information Framework 等银行业标准，实现语义统一与模块化服务边界；增强系统的互操作性与标准合规性。

我们得到了什么？

• 弹性与连续性的革命​：Stand-In模式将核心停机从“灾难”变为“可管理的服务降级”，极大提升了业务连续性。
• 解耦开发能力：产品团队可绕开主机耦合，直接基于数据服务层构建灾备能力，实时风控等功能，交付加快；
• 开放 API 驱动：支持开放银行、第三方金融机构接入，实现更灵活生态协同及合作创新，符合当前数字银行趋势。

Modern Core Banking and Wealth Platforms: Who’s Leading with Real Contracts (2019–2025)

https://www.avaloq.com/services/ecosystem

1. 概念

1. 幂等性 + 事务性
   • Kafka 的 enable.idempotence=true 解决了 生产端的消息重复发送问题，保证“至多一次” → “恰好一次”。
   • transactional.id + 事务 API 则让生产者能把多个写操作当作原子单元，要么全写入，要么全不写。
2. 消费者端隔离级别
   • isolation.level=read_committed 确保消费端只读取 提交成功的事务消息，不会读到失败/未提交的写入。
   • 这相当于 SQL 里的 READ COMMITTED 隔离级别。
3. 两阶段提交（2PC）与事务日志
   • Kafka 内部事务机制不是严格意义上的 分布式 XA 2PC，而是 Producer Coordinator + Transaction Log 的轻量实现。
   • 当你把多个 Topic/Partition 的消息放在一个事务里时，Kafka 会写一条 事务日志（txn log），由 Coordinator 来决定事务的提交/中止状态，消费者依赖 txn log 过滤未提交消息。
   • 所以它更像是 “Kafka 内部的两阶段提交”，如果要与外部数据库（如 MySQL、Redis）做一致性，仍需要 外部协调机制（典型是 Outbox Pattern）。

2. 工程实践

在金融支付类系统里，通常会结合以下手段来确保可靠性：

• 生产端配置最佳实践

  1 2 3 4 5

  enable.idempotence=true # 解决了生产端的消息重复发送问题，保证“至多一次” → “恰好一次”。 acks=all # 确保 ISR 同步确认，确保消息不重复 retries=Integer.MAX_VALUE # 确保消息不丢失 max.in.flight=1 # 避免并发请求导致的乱序 transactional.id=tx-producer-001

• 消费端配置最佳实践

  1 2 3 4

  isolation.level=read_committed enable.auto.commit=false # 结合事务手动提交offset # offset 也写入 Kafka 的事务，确保消息消费与结果提交原子化。 # 常见模式是 Kafka + DB 的事务性写入（即 Outbox Pattern）

• 幂等消费（Exactly Once Processing）
  • 即使 Kafka 层面保证了 “Exactly Once Delivery”，但在消费者更新外部存储（数据库、账本系统）时，仍要确保幂等性。
  • 常见做法：
    • 使用 唯一事务ID/流水号 作为幂等键
    • 在数据库侧维护 dedup 表/唯一索引，避免重复扣款

3. 金融场景案例

1. 支付宝/微信支付 - 支付链路
   • Kafka 事务常用于 支付事件流，比如：
     • 扣款事件（资金冻结）
     • 风控事件（交易审核）
     • 清算/记账事件（账本入账）
   • 如果任何一步失败，整个事务会被中止，消费者端不会看到“半成品交易”。
2. 证券交易所撮合系统
   • 撮合引擎把订单事件写入 Kafka，撮合成功后再写入交易结果事件，两者要么同时写入，要么同时回滚。
   • 避免出现 “订单被接收但未撮合成功” 这种不一致。
3. 银行账务系统（Outbox + Kafka EOS）
   • 常见设计是 双写一致性：
     • 业务库写账务流水（Outbox 表）
     • Kafka Connect CDC 监听 Outbox 表 → 推送到 Kafka → 消费到清算/风控服务
   • Outbox 表和账务写操作在同一数据库事务中完成，Kafka 端依赖 EOS 保证消息不丢不重。

总结：Kafka EOS 只能保证 Kafka 内部端到端不丢不重，如果要与外部系统（DB/账本）做事务一致性，需要使用 Outbox Pattern 或幂等消费 来兜底。