DEV Community: shusukeO

Generating 20 Multilingual Promo Videos from React Code with Remotion

shusukeO — Wed, 25 Feb 2026 00:41:22 +0000

I run Amida-san, an online Amidakuji (lottery ladder) service. For the Product Hunt launch, I needed a 30-second demo video, a 15-second clip for X, and a calmer pitch version -- each in English, Japanese, Chinese, and Korean.

You can see the actual videos on the Amida-san top page.

A promo video embedded on the landing page, showing the Amidakuji animation scene.

Doing this manually in a video editor was not realistic. Instead, I wrote everything as React components. Remotion converts JSX to MP4 -- scenes are functions, translations are props, and rendering is reproducible.

A single npm run video:render:all command generates all 20 videos (5 versions x 4 languages) in one go.

Architecture -- A Standalone Subproject

Remotion ships with heavy dependencies: @remotion/bundler, @remotion/renderer, Webpack toolchain, and ffmpeg bindings. Mixing them into a Vite-based React app bloats node_modules and causes version conflicts.

I separated it into a subproject with its own package.json under a video/ directory.

project-root/
  package.json              # Main app (Vite + React)
  video/
    package.json            # Remotion subproject
    src/
      compositions/         # 6 compositions
      scenes/               # 10 reusable scenes
      constants/            # Render config, Amidakuji config
      components/           # UI parts (Caption, etc.)
    scripts/
      generate-promo-video.ts   # Single video render
      render-all-videos.ts      # 20-video batch render
  src/
    shared/
      videoMetadata.ts      # Metadata shared between main app and video

Iterating with Remotion Studio

During development, npx remotion studio launches a browser-based editor. You select compositions from the sidebar and scrub the timeline to inspect frame by frame.

Remotion Studio. Composition list on the left, timeline with Sequence layout at the bottom.

Switch the language prop from the sidebar to preview each language version on the spot -- changes hot-reload instantly. Being able to fine-tune timing in the browser before rendering to MP4 is one of Remotion's advantages.

Composition Versioning -- 5 Formats

Different platforms require different videos, so I prepared 5 versions:

Version	Duration	Target	Style
A	~50s	Product Hunt (full demo)	Problem-solution
B	~43s	Product Hunt (visual-first)	Animation-driven
C	30s	General purpose (recommended)	Balanced
D	15s	X, TikTok, social media	Hook + CTA only
E	30s	Business / pitch deck	Restrained animations

Each version is an independent composition component (MainPromoA.tsx through MainPromoE.tsx) that assembles scenes with Remotion's <Sequence>. Here is the structure for the 30-second version C:

export const MainPromoC: React.FC<Props> = ({ language }) => {
  const introDuration = 3 * FPS;
  const amidaDuration = 11 * FPS;
  const ballDuration = 10 * FPS;
  const featuresDuration = 3 * FPS;
  const ctaDuration = 3 * FPS;

  return (
    <AbsoluteFill>
      <Audio src={staticFile("audio/bgm.mp3")} volume={0.4} />

      <Sequence from={0} durationInFrames={introDuration}>
        <IntroSceneV2 language={language} />
      </Sequence>

      <Sequence from={introDuration} durationInFrames={amidaDuration}>
        <Amida2DScene
          language={language}
          showWebAppDemo
          videoDelayFrames={6 * FPS}
        />
      </Sequence>

      <Sequence
        from={introDuration + amidaDuration}
        durationInFrames={ballDuration}
      >
        <BallAnimationScene language={language} showWebAppDemo showAnimation />
      </Sequence>

      <Sequence
        from={introDuration + amidaDuration + ballDuration}
        durationInFrames={featuresDuration}
      >
        <FeaturesGridScene language={language} />
      </Sequence>

      <Sequence
        from={introDuration + amidaDuration + ballDuration + featuresDuration}
        durationInFrames={ctaDuration}
      >
        <CTAScene language={language} />
      </Sequence>
    </AbsoluteFill>
  );
};

Multilingual Support and Cultural Adaptation

Each scene receives a language prop ('en' | 'ja' | 'zh' | 'ko') and selects display content from a local text map.

const texts = {
  en: {
    hook: "Can your team trust the lottery?",
    proof: "Trusted by 10,000+ users",
    solution: "Everyone participates. Nobody cheats.",
  },
  ja: {
    hook: "Are the drawings really fair?",
    proof: "Used by 10,000+ people",
    solution: "Everyone joins. Zero fraud.",
  },
  zh: {
    hook: "Is your drawing really fair?",
    proof: "Trusted by 10,000+ users",
    solution: "Everyone participates. Zero cheating.",
  },
  ko: {
    hook: "Is your lottery really fair?",
    proof: "Used by 10,000+ people",
    solution: "Everyone participates. Zero fraud.",
  },
};

Rather than literal translations, natural-sounding expressions take priority in each language. Fonts also switch per language using system fonts.

Reusable Scene Components

The 5 compositions share 10 scene components:

Scene	Used in	Role
IntroSceneV2	C, D	Spring-scaled hook
IntroScene	A, B	Longer narrative intro
IntroSceneSubtle	E	Restrained fade-in intro
Amida2DScene	A, B, C	SVG Amidakuji animation
BallAnimationScene	A, B, C	Ball drop + web app demo
FeaturesScene	A	Feature walkthrough
FeaturesGridScene	B, C	Compact feature grid
FeaturesGridSceneSubtle	E	Restrained feature grid
CTAScene	A, B, C, D	Standard CTA
CTASceneSubtle	E	Business-oriented CTA

Layout constants are centralized in amidaConfig.ts and shared between the animation scene and ball-drop scene.

Batch Rendering -- Bundle Once, Render 20 Times

The key to batch processing is minimizing bundle() calls. Remotion's bundle() runs Webpack internally, which is expensive. The batch script runs bundle() once and loops renderMedia() 20 times against the same bundle.

const renderAllVideos = async () => {
  // Bundle once
  const bundled = await bundle({
    entryPoint: path.join(VIDEO_DIR, "src", "index.ts"),
    webpackOverride: (config) => config,
  });

  // Render 20 times sequentially
  for (const comp of compositions) {
    const composition = await selectComposition({
      serveUrl: bundled,
      id: comp.id,
      inputProps: comp.inputProps,
    });

    await renderMedia({
      composition,
      serveUrl: bundled,
      codec: "h264",
      outputLocation: path.join(OUTPUT_DIR, comp.filename),
      inputProps: comp.inputProps,
    });
  }
};

A flat array enumerates all combinations of composition ID and language, which the loop iterates over.

How Each Composition Determines Its Duration

Versions A and B embed actual web app screen recordings. Since recording length varies by language (the Japanese demo is longer), calculateMetadata resolves duration dynamically at render time.

<Composition
  id="MainPromoA"
  component={MainPromoA}
  durationInFrames={300} // Initial placeholder
  calculateMetadata={async ({ props }) => {
    const durations = await calculatePromoDuration(props.language);
    const totalDuration =
      introDuration +
      durations.amidaSceneDuration +
      durations.ballSceneDuration +
      featuresDuration +
      ctaDuration;
    return {
      durationInFrames: totalDuration,
      props: { ...props, ...durations },
    };
  }}
/>

Conclusion

Adding a new language means adding entries to each scene's text map and appending 4 lines to the composition matrix. Adding a new version just requires one composition file that rearranges existing scenes.

All 20 videos, 5 versions, 4 languages -- the entire pipeline regenerates with a single command.

If your product needs multilingual, multi-format video assets, writing videos as React components is a strong option. Want to change a tagline, swap a font, or add a 6th version? That's where the initial setup cost pays off.

If you need a fair, participatory lottery, try Amida-san!

Originally published at shusukedev.com

Claude Code: Personal Practical Notes

shusukeO — Mon, 02 Feb 2026 23:38:22 +0000

Introduction

Claude Code is a CLI tool provided by Anthropic that lets you delegate coding tasks to Claude directly from the terminal.

How Much Code Can It Write?

In my experience, if your codebase and design are solid, Claude Code generates code at a satisfying level.

Transformers generate the next token based on existing context (the codebase and CLAUDE.md). If the existing codebase is poorly written, it generates poorly written code. If you prepare a well-organized codebase and clear rules, you get quality that matches.

It's a tool that excels at obediently and rapidly propagating patterns, which means the weight of human knowledge and every small decision becomes amplified. If you leave a sloppy codebase unattended, the mess spreads rapidly.

Human engineers have an innate drive toward maintainability and a professional ethic of "not cutting corners." LLMs don't have that intrinsic motivation. Ownership of quality must remain with the human.

In my recent personal projects, 99% of code is written through Claude Code. By combining rule enforcement via CLAUDE.md with design through plan mode, I can develop at high speed while maintaining architectural consistency.

Development Flow

Typical Workflow

1. Maintain CLAUDE.md
2. For major features or design decisions, create a discussion doc in docs/todo
3. Request design in plan mode
4. Review and approve the plan, then let it implement
5. Iterate: review -> fix
6. Sync documentation with /sync-docs
7. Git commit

1. Maintain CLAUDE.md

Before starting a new project or feature, I make sure CLAUDE.md is up to date. This helps Claude correctly understand the project's structure and conventions.

2. Create Discussion Documents (for Major Changes)

When design decisions involve trade-offs or require comparing multiple options, I create a discussion document in docs/todo/ before proceeding.

# Prompt example
"I want to discuss state management strategy. Summarize the options and comparisons in docs/todo/state-management.md"

By organizing thoughts in a document before entering plan mode, design rationale is preserved and easier to review later.

3. Request Design in Plan Mode

Rather than jumping straight into implementation, having Claude design first in plan mode tends to produce better results.

# Prompt example
"I want to add XXX feature. Please make a plan first."

In plan mode, Claude explores the codebase and proposes an implementation approach.

4. Review and Approve the Plan

Review the proposed plan and approve it if it looks good. Provide feedback if changes are needed. After approval, Claude writes the code. It may ask questions along the way, which you answer as needed.

5. Review and Fix Iterations

I don't stop at a single review. I iterate multiple times until I'm satisfied.

# Claude review
/review-diff

# Request fixes if issues are found
"Fix the XXX part"

# Review again
/review-diff

I also check diffs visually in my editor. It's safer to combine Claude's review with a human eye check.

If the implementation feels off, it's often faster to git checkout . and start fresh rather than patching. Since regeneration cost is low with Claude Code, I find it's better to discard aggressively than to cling to a mediocre implementation.

6. Sync Documentation

Once the implementation is stable and ready to commit, I update the documentation.

/sync-docs

This keeps related documentation in sync with code changes.

7. Commit

I commit with regular git commit. You can ask Claude Code to generate commit messages, but the commit itself is a normal git operation.

Frequently Used Commands

Command	Purpose
`/review-diff`	Review current diff (custom command)
`/sync-docs`	Update docs to match code changes (custom command)
`/clear`	Clear context and start a fresh conversation

/review-diff and /sync-docs are custom commands defined in .claude/commands/. Claude Code lets you create project-specific slash commands.

Whenever I notice I'm repeating the same kind of request, I proactively extract it into a custom command. They're just Markdown files with no dependencies, so they're easy to create.

Prompting Tips

Be Specific

# Bad
"Build a login feature"

# Good
"Add an email/password login feature.
 - API endpoint: POST /api/auth/login
 - Return a JWT token on success
 - Return appropriate status codes on error"

Provide Context

# Specify files
"Add a dark mode toggle button to @src/components/Header.tsx"

# Reference existing implementations
"Create a ProductList component following the same pattern as @src/components/UserList.tsx"

Use Domain-Specific Vocabulary

Since LLMs process meaning in embedding space, I find that using precise software engineering terminology conveys intent more accurately than vague everyday language.

# Bad
"Implement it simply"

# Good
"Implement following YAGNI and KISS principles"

# Bad
"Organize it nicely"

# Good
"Separate responsibilities by layer following Separation of Concerns (SoC)"

Words like "simple" and "clean" are open to broad interpretation, while terms like "YAGNI," "KISS," "SoC," "DRY," and "Single Responsibility Principle" have narrow definitions, leading to less output variance.

Include the Reason

Adding "why" alongside "what" helps Claude make better-informed decisions.

# Bad
"Memoize this function"

# Good
"This function is called on every render and has become a performance bottleneck. I want to memoize it to reduce recalculation"

When you provide the reason, Claude sometimes suggests related optimizations or chooses a more appropriate approach.

Proceed Incrementally

Requesting changes in small units tends to produce higher quality than asking for massive changes at once.

1. "First, define the data model"
2. "Next, implement the repository layer"
3. "Create the UI components"

Writing CLAUDE.md

Minimum Recommended Content

# CLAUDE.md

## Development Commands

npm run dev # Start dev server
npm run build # Build
npm run lint # Run lint
npm run test # Run tests

## Architecture Overview

(Directory structure and layer architecture)

## Development Rules

(Coding conventions and notes)

## Tech Stack

(List technologies used)

Key Points

Explicitly state rules you want Claude to follow (e.g., "Respond in English," "Follow YAGNI principle")
Including build/lint commands allows Claude to run them automatically after changes
Writing an architecture overview helps Claude place code in the right locations

What Humans Should Own

While Claude Code can handle a lot, here are areas where I believe humans should take responsibility.

Architecture and Directory Structure

Humans should decide the project's layer structure and directory layout. Claude places code according to what's written in CLAUDE.md, so if that's not well-maintained, code ends up in unintended locations.

Keep Documentation Current

I keep CLAUDE.md and docs/ up to date to prevent drift from the implementation. Claude trusts the documentation, so stale information leads to incorrect decisions.

Make Design Trade-off Decisions

Trade-offs like performance vs. readability or flexibility vs. simplicity are decisions I make as a human. I can ask Claude to compare and organize options, but the final call should be human.

Review for Design Intent Compliance

Verifying that Claude-generated code follows the decided architecture and design intent is better done by humans. Specifically:

Is the layer structure respected? (e.g., no direct references from presentation to infrastructure layer)
Does it follow naming conventions and coding standards?
Is it consistent with existing design patterns?

In addition to Claude's review via /review-diff, I open diffs in my editor for a visual check. Architecture violations in particular can be missed by Claude, so a human check adds confidence.

Parallel Workflow

Approach

I don't use worktrees. I work in a single workspace. I tried using worktrees to edit multiple branches simultaneously, but the cognitive load of tracking which changes were in which tree was too high.

Instead, I use iTerm2 pane splitting to run multiple Claude Code sessions in parallel. With iTerm2's transparency setting, I position VS Code behind it so I can see diffs in real-time while working in Claude Code.

Session Layout (~3 Sessions per Repository)

Session	Role
Main	Current branch implementation
Research/Plan	Investigation and plan creation for next branch
Review	Review of completed code

I sometimes add lightweight tasks like documentation cleanup on top of these.

Scaling Across Repositories

Since I separate frontend and backend repositories, the above structure exists for each. That means roughly 6 concurrent sessions in total.

Conflict Control

When multiple sessions implement in the same repository, I ensure they don't touch overlapping files. Since I know the target files from the plan mode stage, I allocate responsibilities between sessions at that point.

MCP Server Configuration

MCP Servers I Use

I find it's best to keep MCP servers to a minimum. Too many consume context and seem to reduce accuracy.

MCP Server	Purpose
Serena	Codebase symbol analysis, semantic editing
Context7	Reference latest library documentation
Playwright	Browser automation and E2E testing for frontend

Playwright is only enabled for frontend development projects.

Tips and Notes

Actively request web searches and documentation checks: For library usage or latest API specifications that may be outdated in Claude's training data, I include prompts like "Check the official documentation" or "Search the web for latest info." With MCP servers like Context7, Claude sometimes references documentation proactively.
Enforce build/lint via CLAUDE.md: Writing "Always run npm run lint and npm run build after changes" in CLAUDE.md makes Claude detect and fix build/lint errors on its own, reducing manual debugging.
Detect runtime errors too: Giving Claude access to a local dev server where it can check browser console logs and runtime errors enables it to detect and fix issues that don't surface at build time.
Stay close to defaults: Since Claude Code evolves rapidly, I avoid over-customizing with bespoke workflows. For example, features like subagents may eventually get folded into the default plan mode. Riding the tool's natural evolution keeps maintenance costs low and maximizes benefits.

Conclusion

What I've described here is still a relatively conservative development style that relies heavily on human review. Going forward, I want to experiment with orchestrating multiple agents to see if I can further reduce human intervention.

Originally published at shusukedev.com

CI/CD Pipeline for Solo Developers: Go + GCP + GitHub Actions

shusukeO — Sat, 31 Jan 2026 07:12:47 +0000

I run Amida-san (amida-san.com), a web service with 10,000+ users, as a solo developer. The backend is written in Go and deployed on GCP.

In the age of AI, building a working service has become easier than ever. However, delivering a stable, high-quality experience to users requires more than just shipping code. When you're the only developer, you're also the only one who notices when things break. That's why a solid CI/CD pipeline is essential—it keeps the development-to-deployment loop fast and safe.

This article covers the CI/CD pipeline I built using GitHub Actions + GCP (Cloud Run, Cloud Build) + Terraform.

Code samples in this article are simplified for explanation purposes. Service names, regions, and versions have been changed from actual values.

Tech Stack

Category	Technology
Language	Go
Framework	Gin
Infrastructure	GCP (Cloud Run, Cloud SQL, Secret Manager, Artifact Registry)
IaC	Terraform
CI/CD	GitHub Actions + Cloud Build
Security Scanning	Trivy, gosec
Notifications	Discord Webhook

Architecture Overview

CI Pipeline

Automated Quality Checks

Every push and PR to main triggers the following checks automatically:

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout
      - uses: actions/setup-go

      - name: Generate mocks
        run: make mocks

      - name: Run golangci-lint
        uses: golangci/golangci-lint-action

      - name: Run tests
        run: go test -v -race -coverprofile=coverage.out ./...

      - name: Build
        run: go build -v ./...

Key points:

-race flag detects data races—essential for Go's concurrent patterns
golangci-lint for static analysis with customizable rules via .golangci.yml
mockgen auto-generates mocks in CI, ensuring test reproducibility

AI-Powered PR Reviews

When a PR is created, both Claude and Gemini automatically review the code. Using two different AI models provides diverse perspectives, maintaining review quality even as a solo developer.

Dependabot for Dependency Updates

Five ecosystems are automatically updated on a regular schedule:

updates:
  - package-ecosystem: "gomod"
  - package-ecosystem: "docker"
  - package-ecosystem: "github-actions"
  - package-ecosystem: "terraform"
  - package-ecosystem: "npm"

This covers Go, Docker, GitHub Actions, Terraform, and npm—no layer left behind.

CD Pipeline - Deployment Strategy

Why Manual Triggers?

For solo projects, auto-deploying on merge to main is common. I chose manual triggers (workflow_dispatch) instead, for several reasons.

First, coordinating infrastructure and application changes. For example, DB schema changes and app deploys often need a specific order—"add the column first, then deploy the app."

Second, release tags make it clear which codebase is running in production. When incidents happen, you can immediately identify the exact code version.

And honestly, pressing the deploy button gives you a moment of "okay, let's do this"—a small but real psychological benefit.

Release Tag Convention

Release tags follow the YYYYMMDDB format (e.g., 20250703b). The trailing letter (a, b, c...) handles multiple same-day releases. The date-based format makes it instantly clear when the deployed code was cut.

Deployment Flow

The deployment workflow has three safety mechanisms:

on:
  workflow_dispatch:
    inputs:
      deployment_type:
        type: choice
        options: ["full", "restart"]
      release_tag:
        description: "Release tag (YYYYMMDDB format)"
      confirm_production:
        description: 'Type "DEPLOY" to confirm'

Three Safety Guards:

Confirmation string "DEPLOY" — prevents accidental clicks
Tag format validation — rejects anything not in YYYYMMDDB format
Pre-deploy security scan — gosec vulnerability check + full test suite

Cloud Build Pipeline

steps:
  - id: "test" # Run Go tests
  - id: "build" # Build Docker image
    waitFor: ["test"]
  - id: "push" # Push to Artifact Registry
  - id: "deploy" # Deploy to Cloud Run
  - id: "traffic" # Switch traffic (LATEST=100%)

timeout: "1200s"

Test → Build → Push → Deploy → Traffic switch, executed sequentially via waitFor.

Production Dockerfile

# Build stage
FROM golang:x.xx-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o main .

# Runtime stage
FROM alpine:x.xx
RUN adduser -D appuser
WORKDIR /home/appuser
COPY --from=builder /app/main .
USER appuser
CMD ["./main"]

Security measures:

Multi-stage build minimizes image size
Non-root user (appuser) for runtime execution
CGO_ENABLED=0 for static linking with zero external dependencies

Service Restart (Redeploy Without Code Changes)

When Secret Manager secrets are updated, you may need a new revision without code changes:

gcloud run services update <service-name> \
  --region=<region> \
  --update-annotations=restart-timestamp=$(date +%s)

Just select the restart type to pick up new secrets.

Rollback Strategy

A dedicated rollback workflow enables immediate recovery during incidents:

on:
  workflow_dispatch:
    inputs:
      rollback_target:
        type: choice
        options: ["previous-revision", "specific-revision"]
      revision_id:
        description: "Specific revision ID"
      confirm_rollback:
        description: 'Type "ROLLBACK" to confirm'

Two rollback modes:

Previous revision — instantly revert to the last stable version
Specific revision — specify a revision ID from the deploy notification

Leveraging Cloud Run's revision management, rollback is just a gcloud run services update-traffic call. No rebuild needed—rollback completes in seconds.

Post-rollback health checks (with retries) and Discord notifications confirm recovery.

Infrastructure as Code - Terraform

Module Structure

terraform/
├── environments/<env>/
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   ├── providers.tf
│   └── terraform.tfvars
└── modules/
    ├── cloud-run/       # Cloud Run service
    ├── cloud-sql/       # Database
    ├── auth/            # Authentication
    ├── secret-manager/  # Secret management
    ├── billing/         # Budget alerts
    └── monitoring/      # Monitoring config

Every GCP resource—Cloud Run, Cloud SQL, Firebase, Secret Manager, billing, monitoring—is managed through Terraform.

Plan/Apply Separation with Approval Gates

Plan and Apply are separate workflows. Review the diff from Plan, then execute Apply
Apply requires GitHub Environment production approval
Local terraform apply is prohibited. Only GitHub Actions can apply changes

Workload Identity Federation

- name: Authenticate to Google Cloud
  uses: google-github-actions/auth
  with:
    workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
    service_account: ${{ secrets.SA_EMAIL }}

Instead of storing service account keys (JSON) in GitHub Secrets, Workload Identity Federation uses OIDC authentication. This eliminates key rotation and leakage risks entirely.

Security

This project uses gosec and Trivy at different stages for different purposes:

Tool	Target	When	What it detects
gosec	Go source code	Every push/PR (CI)	Code-level vulnerabilities
Trivy (image)	Built Docker image	Scheduled	Known CVEs in OS packages
Trivy (filesystem)	Entire repository	Scheduled	Known CVEs in Go modules, secret leaks

gosec - Static Security Analysis

gosec runs via golangci-lint on every CI run. It detects issues like:

SQL injection (string concatenation in queries)
Command injection (os/exec with external input)
Hardcoded secrets (passwords/tokens in code)
Weak cryptographic algorithms (MD5, SHA1)
Insecure TLS configurations

Trivy - Scheduled Vulnerability Scanning

name: Security Scan
on:
  schedule:
    - cron: "..." # Scheduled

jobs:
  trivy-image-scan:
    steps:
      - run: docker build -t app:latest .
      - uses: aquasecurity/trivy-action
        with:
          image-ref: "app:latest"
          exit-code: "1"
          severity: "HIGH,CRITICAL"

  trivy-fs-scan:
    steps:
      - uses: aquasecurity/trivy-action
        with:
          scan-type: "fs"
          exit-code: "1"
          severity: "HIGH,CRITICAL"

Trivy checks whether libraries and OS packages contain known vulnerabilities—even if your own code is clean. It runs on a schedule rather than every CI run to keep feedback loops fast. Docker image builds and scans are time-consuming, and dependency vulnerabilities don't change with daily development. HIGH/CRITICAL findings trigger immediate Discord notifications.

No code reaches production without passing gosec + tests during deployment.

Monitoring & Notifications

All CI/CD workflow results (deploy, rollback, Terraform apply, security scans) are sent to Discord. Deploy notifications include revision IDs and monitoring links, ensuring all necessary information is available during incidents.

For the monitoring and observability setup (structured logging, GCP Cloud Monitoring dashboards, error alerts, admin web app), see the companion article: Monitoring & Observability for Solo Developers.

Conclusion

Building this level of CI/CD as a solo developer delivers three key benefits:

Deploy with confidence — tests, static analysis, and security scans run before every deploy, with instant rollback available
Lower operational overhead — automation handles routine tasks (dependency updates, security checks)
Production-grade reliability — maintain the same quality processes as team-based development

Setting up this CI/CD infrastructure took significant effort. But once the foundation is in place, the ongoing cost of worrying "is anything broken?" drops dramatically. The investment pays for itself in sustained peace of mind.

In the AI era, building something that works is easier than ever. But keeping it running reliably is a different challenge entirely—quality gates, safe deploy/rollback mechanisms, continuous security checks. These are the things worth investing in as an engineer.

Originally published at shusukedev.com

Monitoring & Observability for Solo Developers: Go + GCP

shusukeO — Sat, 31 Jan 2026 07:09:54 +0000

I run Amida-san (amida-san.com), a web service with 10,000+ users, as a solo developer. The backend is written in Go and deployed on GCP.

In the previous article, I covered the CI/CD pipeline. This article focuses on monitoring, logging, alerts, and admin tooling—the systems that keep the service running reliably.

A service being "up" and a service being "stable" are two different things. Detecting issues early, identifying root causes quickly, and responding effectively—that's what this monitoring stack is built for.

Architecture Overview

Structured Logging with slog

Why Structured Logs?

Text-based logs make it difficult to trace what happened after the fact. Structured logs enable field-level filtering and aggregation in Cloud Logging.

I adopted log/slog, added to Go's standard library in Go 1.21.

Unified Log Functions

// Consistent log output across all layers
shared.LogInfo(ctx, shared.ComponentInteractor, shared.OpCreateEvent, "Event created",
    shared.LogKeyEventId, event.ID,
    shared.LogKeyUserId, userID)

shared.LogError(ctx, shared.ComponentRepository, shared.OpDBQuery, "Query failed", err,
    shared.LogKeyEventId, eventID)

All log output goes through four functions: LogInfo / LogWarn / LogError / LogDebug. Each automatically attaches:

Component name (Router, Interactor, Repository, etc.)
Operation name (CreateEvent, DBQuery, etc.)
HTTP context (request ID, endpoint, method, remote address, user agent)
Source information (file name, line number)

Log Level Strategy

Each layer uses appropriate log levels:

Level	Usage
Info	Normal operations, user input errors (validation, 404, permission denied)
Warn	Repository-layer Not Found, system concerns (external API delays, retries)
Error	Critical system failures (DB connection failures, unexpected errors)

To avoid duplicate logs, the rule is: log at the Repository layer, skip duplicate logging at the Interactor layer.

Request Logging Middleware

func RequestLoggingMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        ctx := c.Request.Context()

        shared.LogInfo(ctx, shared.ComponentRouter, shared.OpRequestStart,
            "Request started")

        c.Next()

        duration := time.Since(start)
        statusCode := c.Writer.Status()

        if statusCode >= 500 {
            shared.LogWarn(ctx, shared.ComponentRouter, shared.OpRequestCompleted,
                "Request completed with server error",
                shared.LogKeyStatusCode, statusCode,
                "duration_ms", duration.Milliseconds())
        } else {
            shared.LogInfo(ctx, shared.ComponentRouter, shared.OpRequestCompleted,
                "Request completed successfully",
                shared.LogKeyStatusCode, statusCode,
                "duration_ms", duration.Milliseconds())
        }
    }
}

All requests are logged at start and completion, with log levels switching based on status code. 5xx responses use Warn (triggering Discord notifications), while others use Info. The middleware uses Warn rather than Error because the actual error source (Interactor or Repository layer) already logs at Error level—avoiding duplication while enabling per-request anomaly detection.

Request ID Tracking

func HTTPContextMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        requestID := c.GetHeader("X-Request-ID")
        if requestID == "" {
            requestID = generateRequestID() // Random 16-char hex
        }

        ctx := context.WithValue(c.Request.Context(), keys.RequestID, requestID)
        c.Header("X-Request-ID", requestID)
        c.Request = c.Request.WithContext(ctx)
        c.Next()
    }
}

Request IDs are automatically attached to all logs and returned in response headers. This enables cross-cutting traceability for any single request.

Discord Error Alerts

Cloud Logging requires you to actively check for issues. As a solo developer, you need a system that pushes notifications to you when something goes wrong.

Error vs. Warn Notification Strategy

// LogError → Immediate Discord notification (@everyone)
func LogError(ctx context.Context, component LogComponent, operation LogOperation,
    message string, err error, keyValues ...interface{}) {
    logWithLevel(ctx, slog.LevelError, component, operation, message, err, keyValues...)

    if globalDiscordConfig != nil && globalDiscordConfig.Enabled {
        SendDiscordErrorAlert(ctx, globalDiscordConfig.WebhookURL,
            component, operation, message, err, keyValues...)
    }
}

// LogWarn → Buffer and batch send at intervals
func LogWarn(ctx context.Context, component LogComponent, operation LogOperation,
    message string, keyValues ...interface{}) {
    logWithLevel(ctx, slog.LevelWarn, component, operation, message, nil, keyValues...)

    if globalDiscordConfig != nil && globalDiscordConfig.Enabled {
        SendDiscordWarnAlert(ctx, globalDiscordConfig.WebhookURL,
            component, operation, message, nil, keyValues...)
    }
}

Level	Notification Method	Reasoning
Error	Immediate + @everyone	Critical failures need instant attention
Warn	Buffered + batch send	Prevents webhook flooding during spikes

Warn Buffering

Warnings are buffered up to 10 entries and sent as a single message at regular intervals:

Avoids hitting Discord Webhook rate limits
Prevents notification explosion during warning storms
Aggregated view makes it easier to spot trends

Information Included in Notifications

Discord notifications automatically include:

Component name and operation name
Error message
Source information (filename:line number + function name)
Request ID, endpoint, method, remote IP
Business data (user ID, event ID, payment ID, etc.)

With source information, you can identify exactly where in the code the problem occurred just from the notification.

GCP Cloud Monitoring

Terraform-Managed Dashboards and Alerts

All dashboards and alert policies are managed through Terraform. Code-based management ensures reproducibility and change history, rather than manual GCP Console configuration.

Dashboard Layout

A 12-tile dashboard visualizes the following:

Category	Metrics
Cloud Run	CPU usage, memory usage, request count, latency (P95)
Cloud Run	Active instances, idle instances
Cloud SQL	CPU usage, connections, disk usage
Errors	5xx error rate, 4xx vs 5xx breakdown, application error log count

Alert Policies

The following alerts are defined in Terraform, triggering email notifications when thresholds are exceeded:

Alert	Target	Purpose
CPU usage	Cloud Run	Performance degradation signals
Memory usage	Cloud Run	OOM risk
Response time	Cloud Run	User experience degradation
5xx error rate	Cloud Run	Server error occurrence
4xx error rate	Cloud Run	Spike in invalid requests
Active instances	Cloud Run	Unexpected scaling
Idle instances	Cloud Run	Wasted costs
CPU usage	Cloud SQL	Database load
Connections	Cloud SQL	Connection pool exhaustion
Disk usage	Cloud SQL	Storage pressure
App error count	Log-based metric	Application anomalies

# Example: 5xx error rate alert
resource "google_monitoring_alert_policy" "error_rate" {
  display_name = "High Error Rate"

  conditions {
    display_name = "HTTP 5xx error rate"
    condition_threshold {
      filter     = "... metric.type=\"run.googleapis.com/request_count\" AND metric.label.response_code_class=\"5xx\""
      comparison = "COMPARISON_GT"
      threshold_value = var.error_rate_threshold

      aggregations {
        alignment_period   = "60s"
        per_series_aligner = "ALIGN_DELTA"
      }
    }
  }

  alert_strategy {
    auto_close = "86400s"
  }
}

All alerts have enable_xxx_alerts variables, allowing per-environment enable/disable control.

Log-Based Metrics

ERROR logs from Cloud Logging are converted into custom metrics and used as alert policy targets:

resource "google_logging_metric" "app_errors" {
  name   = "app_error_count"
  filter = "resource.type=\"cloud_run_revision\" AND severity=\"ERROR\""

  metric_descriptor {
    metric_kind  = "DELTA"
    value_type   = "INT64"
    display_name = "Application Error Count"
  }
}

This makes structured log ERROR output directly alertable through GCP.

Error Handler

func ErrorHandler() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Next()

        lastGinError := c.Errors.Last()
        if lastGinError == nil {
            return
        }

        var appErr *shared.AppError
        if errors.As(lastGinError.Err, &appErr) {
            if gin.Mode() == gin.ReleaseMode {
                // Production: error code and generic message only
                c.JSON(appErr.Status, shared.AppError{
                    Code:    appErr.Code,
                    Message: "An unexpected error occurred.",
                })
            } else {
                // Development: detailed error information
                c.JSON(appErr.Status, appErr)
            }
            return
        }
    }
}

Production hides internal error details from responses (security)
Development returns detailed error information (debugging efficiency)
All errors are recorded in structured logs (traceability)

Admin Web App

A dedicated admin web app (React + TypeScript) provides visibility into service health:

Payment analytics: revenue trends, success rates, daily breakdowns, event rankings
System statistics: real-time user count, event count, participant count
Event management: event status monitoring and operational controls

This surfaces business metrics that are difficult to track through the GCP Console alone.

Conclusion

Here's a summary of the monitoring stack:

Layer	System	Purpose
Application	Structured logging (slog)	Root cause identification
Application	Request ID	Cross-request tracing
Application	Error handler	Appropriate prod/dev responses
Notification	Discord error/warn alerts	Immediate anomaly detection
Infrastructure	GCP Cloud Monitoring	Resource usage visibility
Infrastructure	Alert policies (Terraform)	Automated threshold detection
Business	Admin web app	Business metrics visibility

Building something that works is just the beginning. Keeping it running reliably requires monitoring infrastructure like this. As a solo developer, building systems that detect problems even when you're not watching is essential.

Originally published at shusukedev.com

"Your Books Tell Your Story" — Building an AI Portfolio That Talks Back

shusukeO — Wed, 28 Jan 2026 13:57:09 +0000

This is a submission for the New Year, New You Portfolio Challenge Presented by Google AI

About Me

Hi, I'm Shusuke O. — a Software Engineer from Tokyo. I build technology that harmonizes with nature and human life.

I'm passionate about distributed systems where independent agents interact to create outcomes — rather than rigid, centralized hierarchies. This belief directly inspired this project.

Tech stack: Go, TypeScript, React, Three.js, Kubernetes, Terraform, and more.

Notable project: Amida-san — a distributed lottery platform with 10,000+ users.

Why a Bookshelf?

I've always believed that what you read shapes who you become. When I look at my bookshelf at home, I don't just see titles — I see turning points. The distributed systems book that changed how I think about architecture. The philosophy book that made me question my assumptions about technology. The novel that reminded me why I started coding in the first place.

A traditional portfolio asks: "What can you do?" But I wanted to answer a deeper question: "How do you think?"

That's why I built Talking Bookshelf — an AI-powered bookshelf character that introduces me through my reading history. Not a static list of skills, but a living conversation about the ideas that shaped me.

The concept is simple: Your books tell your story. The bookshelf knows what I've read, my thoughts on each book, and can have natural conversations with visitors about my interests, skills, and experiences.

Portfolio

https://talkingbookshelf.com/demo

Try it out! Ask the bookshelf anything — about my favorite books, technical skills, or what I'm currently reading.

How I Built It

Tech Stack

Layer	Technology
Backend	Go 1.24 + Gin
AI Agent	Google ADK (Agent Development Kit) v0.3.0
LLM	Gemini 2.5 Flash + Flash Lite
Frontend	React 19 + TypeScript + Vite
UI	Material UI 7 + Framer Motion
Hosting	Google Cloud Run
i18n	i18next (English/Japanese)

Architecture

The core of this project is an AI Agent built with Google's ADK (Agent Development Kit). The bookshelf character is powered by Gemini 2.5 Flash (with Flash Lite for validation) and has access to three function-calling tools:

search_books — Search my reading history by keyword
get_book_details — Retrieve detailed information about a specific book, including my personal notes
get_reading_stats — Get statistics about my reading habits (total books, favorite genres, etc.)

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Visitor   │────▶│  Bookshelf  │────▶│   Gemini    │
│             │◀────│    Agent    │◀────│ 2.5 Flash   │
                          │             + Flash Lite │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
                    ┌──────┴──────┐
                    │  Function   │
                    │   Calling   │
                    │    Tools    │
                    └─────────────┘

Why Gemini 2.5 Flash / Flash Lite & ADK?

I chose Gemini 2.5 Flash for its low latency (critical for conversational UX) and strong function-calling capabilities. The model reliably decides when to call tools and handles multi-turn context well.

Google ADK v0.3.0 made building the agent straightforward. Defining tools is declarative and session management is built-in. Here's the core agent setup:

agent := genkit.DefineAgent(
    "bookshelf",
    &genkit.AgentOptions{
        Model: "googleai/gemini-2.5-flash",
        Tools: []genkit.Tool{searchBooks, getBookDetails, getReadingStats},
    },
)

Before ADK, I built agents from scratch — and it was painful. Parsing tool calls from LLM responses, executing them, feeding results back, handling the "should I call another tool?" loop... all manual. Multi-turn conversation? I had to manage session state myself, worry about token limits, and implement context truncation.

ADK handles all of this. The tool execution loop is automatic. Session management is built-in. I just define my tools declaratively and focus on the actual product experience — not the plumbing.

I also use a two-model strategy for optimal UX:

Gemini 2.5 Flash — Main agent for conversation and function calling (quality matters here)
Gemini 2.5 Flash Lite — Validation pipeline for hallucination correction (speed matters here)

When the validation pipeline detects a hallucination, Flash Lite generates a corrected response instantly. Users don't notice the extra safety layer because the lightweight model keeps latency low.

Character Design

The bookshelf has a wooden, cozy design with:

Eyes (glasses) that blink and react
A mouth (made of books) that animates when speaking
Hands that wave during greetings
Emotional states: idle, thinking, talking, surprised

The character creates an approachable, friendly atmosphere that encourages visitors to explore through conversation.

What I'm Most Proud Of

1. From Static Pages to Personal Conversations

Traditional portfolios are fundamentally one-way communication. You write about yourself, list your projects, and hope visitors read it. But here's the problem: visitors don't know what questions to ask. They skim, maybe click a link or two, and leave.

Talking Bookshelf flips this model. Instead of presenting information, it responds to curiosity. Visitors can ask "What's your favorite book?" or "Do you have any books about AI?" — and get answers grounded in my actual reading history. It's a simple interaction, but it transforms passive browsing into active discovery.

2. The Philosophy: Celebrating Individuality, Not Averages

Most platforms today reduce people to averaged metrics — star ratings, follower counts, standardized skill assessments. Your uniqueness gets flattened into comparable numbers.

This project takes the opposite approach: embrace the individual.

The bookshelf has its own distinct personality — not a generic assistant
My reading list reflects my specific journey, not algorithmic recommendations
Every conversation is unique to the visitor's curiosity

The result? An interaction that feels personal, not templated. You're not browsing a profile — you're meeting a character with opinions, favorites, and quirks.

3. Messy Notes, Coherent Answers

You don't need polished writing to create meaningful conversations.

I just jot down whatever comes to mind after finishing a book:

"This finally made distributed consensus click for me"
"Reminds me of that paper on event sourcing..."

When a visitor asks about microservices, the AI synthesizes these fragments into a coherent response — reflecting how I actually think, not how I've learned to market myself.

A portfolio that grows naturally as I read, without the pressure of "content creation."

4. Solving AI Hallucination: The Validation Pipeline

One critical challenge with AI-powered portfolios: hallucination. The agent might confidently claim I read books I've never touched, or misrepresent my opinions.

I built a validation pipeline to solve this:

BookAnnotationValidator — Ensures every book reference actually exists in my data
ContentValidator — Cross-checks claims against my actual notes using Flash Lite
ResponseCorrector — Automatically regenerates responses that fail validation

This means visitors can trust what the bookshelf says. It's grounded in real data, not AI imagination.

Final Thoughts

This project started as a contest entry — but I'm having so much fun building it that I've decided to keep going.

Beyond the technical side, I'm also exploring what it truly means to talk about books — how to craft conversations that feel substantial and rewarding, not just informative.

I'm continuing to develop this project at talkingbookshelf.com — exploring how this concept could help others share their reading journeys too.

Thanks for reading. Feel free to chat with my bookshelf and see what I've been reading.

Building a Full-Stack App with 400K GitHub Additions Solo Using Claude Code in 2025

shusukeO — Mon, 22 Dec 2025 14:57:36 +0000

Introduction

In 2025, I built a full-stack application with infrastructure solo with Claude Code, accumulating about 400,000 GitHub additions over two years.

This is a large-scale project for solo development. Leaving everything to AI leads to chaos. How do you design and collaborate to avoid breakdown? I'll share the knowledge gained from two years of trial and error.

My first experience with AI development was in 2022 with GitHub Copilot's tab completion. The experience of pressing Tab and watching code appear was astonishing. Since then, my development style has evolved along with AI tools, and now Claude Code is my main partner.

Here's the scale of the project:

GitHub additions (cumulative): ~400,000 (across 2 repositories)
Current codebase: ~230,000 lines (~120,000 effective code via cloc)
Development period: ~2 years
Production deployments: 500+
Users: 10,000+ (growing particularly fast in recent months)

The high cumulative additions reflect aggressive iteration enabled by AI: infrastructure migration from VPS to GCP, major refactoring with DB migrations, and rapid cycles of prototyping, discarding, and reimplementing features.

Initially, this was an experimental personal project, so I had the freedom to try various AI tools and approaches. This allowed the project to evolve as a truly AI-native development endeavor.

The tools I used evolved along with the AI development landscape:

Early stage: GitHub Copilot tab completion
Mid stage: GitHub Copilot agent mode
Current: Claude Code

I tried other tools as well, but none led to sustained use.

What I Built: Amida-san

https://amida-san.com

"Amida-san" is a service for creating online Amidakuji (Japanese ladder lottery). You share a URL, and all participants connect lines to build the Amidakuji together. Since everyone participates in the lottery process, transparency is ensured. It's useful for situations requiring fair draws—like choosing a party organizer at work, deciding seating arrangements, assigning team responsibilities, or prize drawings.

The easiest way to understand is to try it yourself. There's a sample available, so you can test it even alone!

Key Features

Share URL for group participation (up to 299 people)
No user registration required
Fair and transparent lottery process

Technical Stack Overview

This project consists of two repositories:

Frontend
- React web application, Cloudflare Pages hosting, Cloudflare Workers edge processing
Backend + Infrastructure
- Go server application, GCP infrastructure built with Terraform

Evolution of AI Tools and Design Scope Changes

As AI tools evolved, the "design scope" I consider during development changed significantly.

Tool	Design Scope	What I Focused On
GitHub Copilot Tab Completion	Function level	Embedding implementation intent in names
GitHub Copilot Agent	Use case level	Following existing patterns
Claude Code	Feature/Branch level	Defining requirements and specifications

As tools evolved, I could think about design in larger units. Below, I'll detail each era.

The GitHub Copilot Tab Completion Era

In the early development phase, I mainly used GitHub Copilot's tab completion. When I first started using it, I remember it couldn't complete as much code at once as it can now, and the accuracy wasn't as high.

What I focused on during this period was program design at the function level. I was mindful of appropriate granularity and responsibilities, and naming things properly.

When trying to create functions with overly broad responsibilities, unintended features would get implemented, or code duplicating existing implementations would frequently appear within functions.

Regarding naming, names that reveal internal implementation are important. For example, if I want a function that processes in milliseconds, I name it delayMs—including Ms in the name. This is exactly the "pack information into names" principle from the book "The Art of Readable Code." The same principles that make code readable to humans are effective for getting AI to generate appropriate code.

The scope I considered during design was: composing functions to build the entire codebase, and embedding specific implementation intent into function names.

The GitHub Copilot Agent Era

As development entered the mid-stage, GitHub Copilot began incorporating agent mode. I don't remember the exact timing, but it was around when Cline was also gaining attention. I tried Cline too, but continued with GitHub Copilot for cost reasons.

The project state at this time:

Basic architecture was complete
Essential APIs were starting to come together
Implementing features for actual use cases

What I focused on when developing with GitHub Copilot agents was whether existing implementation patterns could be followed, and for complex features, whether changes could be contained to about one file.

To make agent-driven implementation smooth, the project's existing design matters. Because the architecture was well-organized, implementations following existing patterns went relatively well—things like data-passing implementations that were mostly just renamed. Fine details required manual fixes, but implementations that had been a burden due to sheer volume became much easier.

Conversely, using agents without organized design leads to inconsistent implementations or additions that ignore existing patterns. To maximize agent capabilities, it's essential for humans to prepare an appropriate design foundation first.

The agent's ability to find patterns across multiple files and actively make changes fundamentally changed the development experience.

However, I was cautious about generating complex logic. The following cases failed to produce intended implementations:

Understanding relationships between multiple files with specific purposes
Cases requiring efficient algorithms

For this reason, I tried to keep generation requests to roughly single-file scope. The design scope I had in mind was use-case level for a single entity.

The Claude Code Era

I started using Claude Code around spring of this year. There are other promising agent tools, but it remains my primary tool.

Since adopting Claude Code, the frequency of writing code directly in an editor has plummeted. Most of my input now goes to Claude Code instructions in the terminal.

What I focus on with Claude Code is precise requirements and specification definition. Specifically, clarifying:

The purpose of changes in that branch
Understanding the implementation approach and potential pitfalls
Choices that consider trade-offs

This is one of the most challenging parts of engineering, but once you clear this, implementations come together smoothly as intended.

Claude Code has high tool maturity and good feel. Beyond basic LLM performance improvements, it excels at:

Codebase search
Appropriate documentation reading
Context management experience

Using Claude Code

Organize File Structure and Architecture

This is an essential step when starting any project of reasonable scale.

AI collects information from the existing codebase and makes additions. When the codebase framework is organized:

Context can be collected efficiently
Appropriate implementations can be added with minimal changes

Without organization, inefficient context collection occurs and messy implementations get generated.

The frontend has a simple layered architecture. While various best practices exist, I adopted a feature-based structure. Under src, there are three main folders:

application - Settings and configurations for the entire application
domain - Application domain knowledge and use cases
presentation - Logic for appearance and interactions

- src
  - application
    - config
    - state
  - domain
    - features (Redux Slice)
    - types
  - presentation
    - components
    - pages
    - hooks
    - router

The backend follows a clean architecture structure. As a design principle, I judged that strictly adhering to clean architecture would be overkill, so I simplified some DB-related implementations. It consists of three main layers:

application - Concrete application-specific implementations
domain - Domain and its use cases
presentation - HTTP server routing, etc.

- pkg
  - application
    - config
    - db
    - interactors
    - repositoryimpl
  - domain
    - entity
    - usecases
  - presentation
    - handler
    - controller

Organize Documentation

Once project structure is organized, next is documentation. AI collects context and plans implementations based on documentation. This enables finding needed implementations immediately and formulating intended directions.

README.md

My README.md includes:

Repository purpose
Key features
File structure
Local run/debug instructions
Deployment methods
Paths to documentation

The following three are particularly important for AI development:

1. Local run/debug instructions

Enables smooth verification after AI implementation. If you write "verify debug logs after implementation" in an instruction document like Claude.md, implementation and debugging can be done in a single request.

2. Deployment methods

AI can understand where the application runs and make appropriate plans. Prevents off-target deployment suggestions after implementation.

3. Paths to documentation

I've become more conscious of leaving documentation for AI development. I briefly describe what files exist under the docs directory.

docs Directory

The docs structure:

- api
- business
- todo
- done
- README.md

What's distinctive is the todo and done directories. todo contains implementation planning documents. When starting any implementation, I begin by creating this todo document. Once it's created, I start a new session for implementation, and move it to done when complete. This suppresses context bloat and preserves detailed implementation intent per branch.

Claude.md

I keep Claude.md concise at a few hundred lines. Contents include:

Documentation writing guidelines
Project architecture
Implementation guidelines
Testing guidelines
Local run instructions
MCP utilization

Previously, I wrote detailed specifications with concrete examples. However, I sense that not over-specifying tends to work better. Now I write as simply as possible.

What I pay attention to is using words with heavier domain knowledge.

For example, suppose I want minimal implementation without over-engineering for the future. A naive instruction would be "implement simply."

The word "simple" is a generic word used in various everyday contexts. Imagining Word2Vec vector space, it exists in a place surrounded by miscellaneous words—a light word with weak characteristics.

On the other hand, if I write "follow YAGNI and KISS principles" for this case, these become sharper terms within the narrow field of software engineering. Using such words can steer LLM reasoning in appropriate directions with minimal context.

MCP

Various MCPs exist, but I only use these three:

Unnecessary MCPs cause context pollution. Most tool invocations are sufficient via CLI. I believe it's best to only introduce MCPs for tools that are truly necessary and consistently high-priority.

Serena - Semantic code search and editing tool
Context7 - Fetch latest documentation
Playwright - Browser automation

Development Flow

I proceed in three phases: design, implementation, and review. Here I'll introduce the overview—detailed tool usage and specific flows will be covered in a future article.

Design Phase

When developing new features, I first consult with Claude Code on design. I use plan mode and create the aforementioned todo files while progressing through design. The quality of this design determines most of what follows. I carefully choose words, provide necessary and sufficient information, and have it gather required context.

Implementation Phase

Basically, just have it implement according to the plan. I watch the implementation in the editor, immediately press ESC to interrupt if it starts doing something unintended, or inject necessary information.

Review, Debugging, and Troubleshooting

Currently, this phase takes the most time. I read through the code AI wrote. If something's unclear, I ask questions or request additional fixes. I also verify functionality. It still produces tricky bugs or unnatural implementations, so I can't let my guard down. I expect this to decrease as AI evolves, so I'm handling it patiently.

Summary

In 2025, I built a full-stack application solo with Claude Code, accumulating about 400,000 GitHub additions over two years.

What I can say from this experience:

Large-scale full-stack + infrastructure is achievable with AI development
However, collaboration matters, not leaving everything to AI
Human creativity and judgment remain crucial

AI coding tools have fundamentally changed the development environment. And they will continue to change.

I hope this article helps with your AI development projects!
If I have time in the future, I plan to write more detailed articles about Claude Code mastery.

Bonus: Try Amida-san

https://amida-san.com

Please use it when you need fair draws—like choosing a party organizer at work, assigning team responsibilities, or prize drawings.

If you have feedback or thoughts about this article or Amida-san, I'd love to hear them!

Originally published at shusukedev.com

Automating Blog Cross-posting to DEV and X with GitHub Actions

shusukeO — Fri, 21 Nov 2025 15:01:32 +0000

Publishing a blog post shouldn't require manually copying content to multiple platforms. I built a GitHub Actions workflow that deploys to Cloudflare, cross-posts to Dev.to, and posts to X—all with one click.

The Problem

Every time I publish a blog post, I need to:

Deploy to Cloudflare Workers
Copy the content to Dev.to (with proper canonical URL)
Post to X about it

Doing this manually is tedious and error-prone. I wanted a single workflow that handles everything.

Architecture Overview

publish-blog-post.yml (GitHub Actions)
├── Deploy to Cloudflare Workers
├── Cross-post to Dev.to (with canonical_url)
├── Post to X (using existing OAuth 2.0 system)
└── Save IDs to frontmatter → auto-commit

The key insight: track what's already published in frontmatter. This prevents duplicate posts and enables article updates on Dev.to.

Implementation

Frontmatter Schema

Each blog post has optional fields for tracking published state:

---
title: "My Post"
description: "Post description"
pubDate: 2025-01-01
tags: ["tag1", "tag2"]
draft: false
devtoId: 123456        # Auto-set after Dev.to publish
tweetId: "1234567890"  # Auto-set after posting to X
---

Dev.to Publishing Script

The script checks if devtoId exists to determine create vs. update:

// scripts/publish-devto.ts
import { readPost, updateFrontmatter, getCanonicalUrl } from './lib/frontmatter.js';
import { createArticle, updateArticle } from './lib/devto.js';

const post = readPost(slug);
const canonicalUrl = getCanonicalUrl(slug);

// Add footer linking to original
const footer = `

---

*Originally published at [shusukedev.com](${canonicalUrl})*`;

const article = {
  title: post.frontmatter.title,
  body_markdown: post.content + footer,
  published: true,
  tags: post.frontmatter.tags.slice(0, 4),
  canonical_url: canonicalUrl,
};

if (post.frontmatter.devtoId) {
  // Update existing
  await updateArticle(post.frontmatter.devtoId, article);
} else {
  // Create new
  const result = await createArticle(article);
  updateFrontmatter(slug, { devtoId: result.id });
}

X Integration

The script generates a scheduled post YAML file:

// scripts/tweet-post.ts
const postText = `New post: ${title}

${description}

${url}`;

const yamlContent = `platform: twitter
status: scheduled
scheduledFor: ${new Date().toISOString()}
content: |
${postText.split('\n').map(line => '  ' + line).join('\n')}
`;

writeFileSync(`posts/twitter/scheduled/${fileName}`, yamlContent);

The workflow then calls npm run post:publish to post.

GitHub Actions Workflow

name: Publish Blog Post

on:
  workflow_dispatch:
    inputs:
      slug:
        description: 'Article slug'
        required: true
      skip_twitter:
        type: boolean
        default: false
      skip_devto:
        type: boolean
        default: false

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4

      # Deploy blog
      - run: npm ci
        working-directory: shusukedev-blog
      - run: npm run build
        working-directory: shusukedev-blog
      - run: npx wrangler deploy
        working-directory: shusukedev-blog

      # Cross-post to Dev.to
      - run: npm run post:devto -- ${{ inputs.slug }}
        if: ${{ !inputs.skip_devto }}
        working-directory: shusukedev-blog

      # Post to X
      - run: npm run post:tweet -- ${{ inputs.slug }}
        if: ${{ !inputs.skip_twitter }}
        working-directory: shusukedev-blog
      - run: npm run post:publish ${{ steps.tweet.outputs.TWEET_FILE_PATH }}
        if: ${{ !inputs.skip_twitter }}

      # Commit ID updates
      - run: |
          git add .
          git commit -m "Publish: ${{ inputs.slug }}" || true
          git push

SEO Considerations

Cross-posting the same content can hurt SEO if not done correctly. Two safeguards:

canonical_url - Tells search engines the original is on shusukedev.com
Footer link - Visible to readers: "Originally published at shusukedev.com"

Dev.to respects canonical URLs and won't compete with your original in search results.

Update Behavior

Service	First Run	Subsequent Runs
Cloudflare	Deploy	Re-deploy
Dev.to	Create (POST)	Update (PUT)
X	Post	Skip (tweetId exists)

This means I can fix typos and the Dev.to version stays in sync, while X doesn't spam followers.

Tips

Preventing accidental links on X: X automatically converts domain-like strings (e.g., Dev.to) into clickable links, which can look messy. My script inserts a zero-width space (U+200B) after the dot to prevent this: Dev.\u200Bto looks identical but won't be linked.

Conclusion

With ~200 lines of TypeScript and a GitHub Actions workflow, I now publish everywhere with one click. The frontmatter tracking pattern could extend to other platforms like Hashnode or Medium.

The full implementation is in my blog's repository. Feel free to adapt it for your own workflow.

Originally published at shusukedev.com

Building a Technical Blog with Astro + Cloudflare

shusukeO — Fri, 21 Nov 2025 12:35:49 +0000

All tools used in this guide are free. Astro, Cloudflare Workers (free tier), and Durable Objects (free tier) allow you to build and deploy a fully functional blog at zero cost.

This blog is built using Astro 5 and Cloudflare's edge computing technology. Here's how to build a fast and scalable blog system from scratch.

Tech Stack

Frontend

Astro 5 - Static site generator with Content Collections support
MDX - Markdown + React components
Tailwind CSS 4 - Utility-first CSS framework

Backend & Infrastructure

Cloudflare Workers - Serverless runtime at the edge
Cloudflare Durable Objects - Globally distributed state management

Why This Stack?

1. Performance

Astro's partial hydration loads JavaScript only where needed
Cloudflare's global edge network provides low-latency access worldwide
Static generation ensures fast initial page loads

2. Scalability

Durable Objects enable serverless state management (view counts, likes)
Pay-as-you-go pricing scales from small to large

3. Developer Experience

MDX allows embedding components in articles
Astro's Content Collections provide type-safe content management
Tailwind CSS 4's new CSS variable-based design system

Interactive Features

One of the key features of this blog is the interactive like button with smooth animations. When users click the like button, they see:

Heart bounce animation - The heart icon scales up and bounces (0.6s)
Count-up animation - The like count fades in from below (0.4s)
Button feedback - The button briefly shrinks on click (0.15s)
Color transition - The heart changes to red with a smooth transition

The like system uses localStorage to track user interactions (up to 10 likes per article) and Durable Objects to persist the total count globally. The blog listing page uses a batch API to fetch stats for all posts in a single request, and bot detection prevents crawlers from inflating view counts. This creates a delightful user experience while maintaining simplicity and performance.

Project Structure

shusukedev-blog/
├── src/
│   ├── content/
│   │   ├── blog/              # Blog posts (MDX)
│   │   │   └── *.mdx
│   │   └── config.ts          # Content Collections schema
│   ├── layouts/
│   │   └── Layout.astro       # Common layout
│   ├── pages/
│   │   ├── index.astro        # Home page
│   │   ├── blog/
│   │   │   ├── index.astro    # Blog listing
│   │   │   └── [...slug].astro # Individual post pages
│   │   └── api/               # API endpoints
│   │       ├── views/[slug].ts
│   │       └── likes/[slug].ts
│   ├── components/
│   │   ├── ViewCount.astro    # View count display
│   │   └── LikeButton.astro   # Like button
│   ├── durable-objects/
│   │   └── ViewCounter.ts     # Durable Object class
│   └── styles/
│       └── global.css
├── astro.config.mjs
├── wrangler.jsonc             # Cloudflare configuration
├── package.json
└── tailwind.config.js

Setup Instructions

1. Create Project

Generate the initial project structure using Astro's official CLI.

npm create astro@latest shusukedev-blog
cd shusukedev-blog

2. Install Dependencies

Add Cloudflare Workers deployment, MDX support, Tailwind CSS styling, type definitions, and build tools.

npm install @astrojs/cloudflare @astrojs/mdx @astrojs/sitemap
npm install @tailwindcss/vite tailwindcss
npm install -D @cloudflare/workers-types esbuild

Package roles:

@astrojs/cloudflare - Adapter for Cloudflare Workers deployment
@astrojs/mdx - MDX (Markdown + JSX) support
@astrojs/sitemap - Automatic sitemap.xml generation for SEO
@tailwindcss/vite - Tailwind CSS Vite plugin
@cloudflare/workers-types - TypeScript type definitions (dev only)
esbuild - Transpile Durable Objects (dev only)

3. Astro Configuration

Define Astro's behavior including MDX, Sitemap, Tailwind CSS integrations, and Cloudflare Workers deployment settings.

astro.config.mjs:

import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";
import tailwindcss from "@tailwindcss/vite";
import cloudflare from "@astrojs/cloudflare";
import sitemap from "@astrojs/sitemap";

export default defineConfig({
  site: "https://shusukedev.com",
  integrations: [mdx(), sitemap()],
  vite: {
    plugins: [tailwindcss()],
  },
  adapter: cloudflare(),
});

4. Define Content Collections Schema

Define type-safe schema for blog post frontmatter (metadata). This enables type checking and editor autocomplete when writing articles.

src/content/config.ts:

import { defineCollection, z } from "astro:content";

const blog = defineCollection({
  type: "content",
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

5. Implement Durable Objects

Implement backend logic to persist view counts and likes for each article. Durable Objects is Cloudflare's globally distributed state management service.

src/durable-objects/ViewCounter.ts:

export interface Env {
  VIEW_COUNTER: DurableObjectNamespace;
}

interface CounterData {
  views: number;
  likes: number;
}

export class ViewCounter {
  state: DurableObjectState;
  env: Env;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
    this.env = env;
  }

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const path = url.pathname;

    try {
      if (path === "/views" && request.method === "POST") {
        return await this.incrementViews();
      }

      if (path === "/likes" && request.method === "POST") {
        return await this.incrementLikes();
      }

      if (path === "/stats" && request.method === "GET") {
        return await this.getStats();
      }

      return new Response("Not Found", { status: 404 });
    } catch (error) {
      console.error("Durable Object fetch error:", error);
      return new Response("Internal Server Error", { status: 500 });
    }
  }

  private async incrementViews(): Promise<Response> {
    const data = await this.getData();
    data.views++;
    await this.state.storage.put("data", data);

    return new Response(JSON.stringify(data), {
      headers: { "Content-Type": "application/json" },
    });
  }

  private async incrementLikes(): Promise<Response> {
    const data = await this.getData();
    data.likes++;
    await this.state.storage.put("data", data);

    return new Response(JSON.stringify(data), {
      headers: { "Content-Type": "application/json" },
    });
  }

  private async getStats(): Promise<Response> {
    const data = await this.getData();

    return new Response(JSON.stringify(data), {
      headers: { "Content-Type": "application/json" },
    });
  }

  private async getData(): Promise<CounterData> {
    const stored = await this.state.storage.get<CounterData>("data");
    return stored || { views: 0, likes: 0 };
  }
}

6. Cloudflare Configuration

Define Cloudflare Workers deployment settings and Durable Objects bindings. This allows Workers to recognize the ViewCounter class and make it available via API.

wrangler.jsonc:

{
  "main": "dist/_worker.js/index.js",
  "name": "shusukedev-blog",
  "workers_dev": false,
  "compatibility_date": "2025-11-18",
  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
  "assets": {
    "binding": "ASSETS",
    "directory": "./dist"
  },
  "observability": {
    "enabled": true
  },
  "durable_objects": {
    "bindings": [
      {
        "name": "VIEW_COUNTER",
        "class_name": "ViewCounter",
        "script_name": "shusukedev-blog"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["ViewCounter"]
    }
  ]
}

7. API Endpoints

Create API routes to communicate with Durable Objects. These endpoints handle view count increments and statistics retrieval for each blog post.

src/pages/api/views/[slug].ts:

import type { APIRoute } from "astro";

export const prerender = false;

export const POST: APIRoute = async ({ params, locals }) => {
  const { slug } = params;

  if (!slug) {
    return new Response(JSON.stringify({ error: "Slug is required" }), {
      status: 400,
      headers: { "Content-Type": "application/json" },
    });
  }

  try {
    const id = locals.runtime.env.VIEW_COUNTER.idFromName(slug);
    const stub = locals.runtime.env.VIEW_COUNTER.get(id);
    const response = await stub.fetch("http://internal/views", {
      method: "POST",
    });
    const data = await response.json();

    return new Response(JSON.stringify(data), {
      status: 200,
      headers: { "Content-Type": "application/json" },
    });
  } catch (error) {
    console.error("Failed to increment views:", error);
    return new Response(
      JSON.stringify({ error: "Failed to increment views" }),
      {
        status: 500,
        headers: { "Content-Type": "application/json" },
      }
    );
  }
};

export const GET: APIRoute = async ({ params, locals }) => {
  const { slug } = params;

  if (!slug) {
    return new Response(JSON.stringify({ error: "Slug is required" }), {
      status: 400,
      headers: { "Content-Type": "application/json" },
    });
  }

  try {
    const id = locals.runtime.env.VIEW_COUNTER.idFromName(slug);
    const stub = locals.runtime.env.VIEW_COUNTER.get(id);
    const response = await stub.fetch("http://internal/stats");
    const data = await response.json();

    return new Response(JSON.stringify(data), {
      status: 200,
      headers: { "Content-Type": "application/json" },
    });
  } catch (error) {
    console.error("Failed to get stats:", error);
    return new Response(JSON.stringify({ error: "Failed to get stats" }), {
      status: 500,
      headers: { "Content-Type": "application/json" },
    });
  }
};

8. Create Blog Posts

Write blog content using MDX format. MDX allows you to use JSX components within Markdown, enabling interactive elements and rich content.

src/content/blog/example.mdx:

---
title: "Post Title"
description: "Post description"
pubDate: 2025-11-20
tags: ["astro", "cloudflare"]
draft: false
---

# Heading

Write your content here.

## Code Blocks

\`\`\`typescript
const greeting = "Hello, World!";
console.log(greeting);
\`\`\`

## Embed Components

import CustomComponent from "../../components/CustomComponent.astro";

<CustomComponent />

Deployment

Local Development

npm run dev

Build

npm run build

Deploy to Cloudflare Workers

npx wrangler deploy

Or use GitHub Actions for automatic deployment:

Set up Cloudflare API token in GitHub Secrets
Configure GitHub Actions workflow
Push to main branch triggers automatic deployment

Design Refinement with Claude Code

Building a blog isn't just about functionality—design matters. I used Claude Code as my design partner throughout the development process.

This approach was inspired by Anthropic's article on improving frontend design through skills. The article highlights a key challenge: LLMs tend to generate generic, "safe" designs. By leveraging Claude Code's design expertise, I avoided the typical "AI-generated" aesthetic.

Dark Mode

Claude Code helped implement dark mode that feels intentional, not just an inverted color scheme:

Prevented FOUC with an inline script checking localStorage and prefers-color-scheme
Subtle borders (gray-200 → gray-800) that define sections without overwhelming the design
Adjusted code block backgrounds for better syntax highlighting in dark mode

Result

The final design avoids common AI-generated patterns while maintaining clean, professional aesthetics. It feels purposeful rather than generic—exactly what the Claude Skills blog post advocates for.

Summary

This stack provides:

Fast loading speeds - Static delivery at the edge + partial hydration
Real-time state management - View counts and likes via Durable Objects
Excellent developer experience - Type-safe Content Collections + MDX
Scalable architecture - Serverless with automatic scaling

Questions? Reach out on X @shusukedev.

Originally published at shusukedev.com

DEV Community: shusukeO

Generating 20 Multilingual Promo Videos from React Code with Remotion

Architecture -- A Standalone Subproject

Iterating with Remotion Studio

Composition Versioning -- 5 Formats

Multilingual Support and Cultural Adaptation

Reusable Scene Components

Batch Rendering -- Bundle Once, Render 20 Times

How Each Composition Determines Its Duration

Conclusion

Claude Code: Personal Practical Notes

Introduction

How Much Code Can It Write?

Development Flow

Typical Workflow

1. Maintain CLAUDE.md

2. Create Discussion Documents (for Major Changes)

3. Request Design in Plan Mode

4. Review and Approve the Plan

5. Review and Fix Iterations

6. Sync Documentation

7. Commit

Frequently Used Commands

Prompting Tips

Be Specific

Provide Context

Use Domain-Specific Vocabulary

Include the Reason

Proceed Incrementally

Writing CLAUDE.md

Minimum Recommended Content

Key Points

What Humans Should Own

Architecture and Directory Structure

Keep Documentation Current

Make Design Trade-off Decisions

Review for Design Intent Compliance

Parallel Workflow

Approach

Session Layout (~3 Sessions per Repository)

Scaling Across Repositories

Conflict Control

MCP Server Configuration

MCP Servers I Use

Tips and Notes

Recommended Reading

Conclusion

CI/CD Pipeline for Solo Developers: Go + GCP + GitHub Actions

Tech Stack

Architecture Overview

CI Pipeline

Automated Quality Checks

AI-Powered PR Reviews

Dependabot for Dependency Updates

CD Pipeline - Deployment Strategy

Why Manual Triggers?

Release Tag Convention

Deployment Flow

Cloud Build Pipeline

Production Dockerfile

Service Restart (Redeploy Without Code Changes)

Rollback Strategy

Infrastructure as Code - Terraform

Module Structure

Plan/Apply Separation with Approval Gates

Workload Identity Federation

Security

gosec - Static Security Analysis

Trivy - Scheduled Vulnerability Scanning

Monitoring & Notifications

Conclusion

Monitoring & Observability for Solo Developers: Go + GCP

Architecture Overview

Structured Logging with slog

Why Structured Logs?

Unified Log Functions

Log Level Strategy

Request Logging Middleware

Request ID Tracking

Discord Error Alerts