AGENTS.md vs CLAUDE.md: How to Give Claude and Codex Separate Rules in the Same Repository
Shiori
What CLAUDE.md and AGENTS.md each do, why separate files are necessary, and how I use shared/ to avoid duplicating common rules.
Blog
Automated Reference URL Verification: Designing a Script to Mechanically Check AI-Generated Links
Shiori
AI can generate URLs for references that do not actually exist. This article covers how the URL-checking script for this site works and how it classifies results.
Balancing Token Savings and Code Quality: A Real Example of Quality Declining from Over-Trimming
Shiori
A record of how reducing AI input context to lower costs led to a decline in output quality, along with criteria for deciding what can and cannot safely be removed.
Building a Validation Script with AI: Automating Consistency Checks for Harness Configuration
Shiori
Manually checking the consistency of configuration files has limits. This article covers the process of building a validation script with AI and why automated detection proved useful.
Building with Astro, Starlight, and Vercel Alongside AI: What I Delegated and What I Checked Myself
Shiori
A firsthand record of configuring a site using Astro, Starlight, and Vercel alongside AI. Covers the role of each tool and a breakdown of which parts of the setup were delegated to AI versus confirmed personally.
Choosing Between Claude and Codex: How I Decide Which AI to Hand Off Work to in the Same Repository
Shiori
The criteria I use to decide whether to work with Claude Code or Codex in the same project, with a specific example of handing off mid-task.
Copyright and Attribution When Treating AI as a Co-Author: This Blog's Policy and Current Understanding
Shiori
Who holds copyright over text that AI generated, and should readers be told? This article explains Japan's current legal understanding and the policy I follow on this blog.
Criteria for Delegating Tasks to AI: Three Axes for Deciding What to Ask AI to Do
Shiori
Three axes for deciding how much to delegate to AI — reversibility, scope of impact, and ease of verification — explained with concrete scenarios.
Defining AI Specialist Tasks with SKILL.md: How Skill Design Improves Reproducibility
Shiori
Repeating the same instructions to an AI every time is less stable than defining procedures as a skill file. This article covers how I designed SKILL.md files for this site and what changed as a result.
Designing a Lessons Log to Prevent Repeated AI Mistakes: How lessons.md Stops the Same Problem from Happening Twice
Shiori
Because AI memory resets between conversations, resolved issues can recur in the next session. This article explains how I designed lessons.md, a log file that AI reads to avoid repeating the same mistakes.
Designing an AI Review Loop for AI Output: What Automated Checks Can and Cannot Prevent
Shiori
Based on experience running an AI reviewer alongside an AI writer, this article clarifies what automated checks reliably detect and where human review remains necessary.
Designing the shared/ Directory: How I Organized Rules, Skills, and Workflows for AI to Reference
Shiori
When the number of rule files for AI grows, knowing what is where becomes difficult. This article explains how I organized them into three categories—rules, skills, and workflows—using the shared/ directory.
Frontmatter Design and Automatic learning_time Normalization: Managing Quality for AI-Generated Articles at Scale
Shiori
When AI generates many articles, frontmatter values can fall out of sync with the actual content. This article explains why I introduced an automatic normalization script for the learning_time field and what consistency gains come from automation.
Handing Work from Claude Code to Codex with Uncommitted Changes
Shiori
What happened when I moved work from Claude Code to Codex with a dirty worktree, and the steps I now follow for a safe handoff.
Handing Work from Claude Code to Codex: Designing and Using an agent-handoff Document
Shiori
How I designed and use an agent-handoff document to transfer work from a Claude Code session to Codex.
How AI Triggered a Production Deployment and Why I Made npm run build Require Approval
Shiori
A record of how a production deployment command ran while I was asking AI to make a separate change, and the approval-required rule I put in place afterward.
How I Built a Site with Vibe Coding: The Full Process from Design to Launch
Shiori
A step-by-step record of building a website from scratch in collaboration with AI. What I delegated to AI and what I decided myself, explained through the actual stages of the project.
How to Use Claude Code Hooks: Real Examples of Adding Custom Processing Before and After Tool Execution
Shiori
Real examples of setting up Claude Code hooks for pre-edit backups and post-edit automatic validation, with notes on how the workflow changed.
How to Write CLAUDE.md and What It Changes: Controlling AI Behavior Through a Project Configuration File
Shiori
CLAUDE.md is the configuration file AI reads first when starting a project. This article explains what to write in it and how it changes AI behavior, with before-and-after examples.
Issues with Mermaid and AI: Five Patterns Where Diagrams Failed to Render Correctly and How I Fixed Them
Shiori
A record of five specific patterns where AI-generated Mermaid diagrams failed to render correctly — including special characters, arrow direction, label length, Japanese text, and nested structures — along with how each was resolved.