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.
Harness Engineering
16 posts with the tag “Harness Engineering”
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.
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.
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.
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 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.
Preventing AI from Modifying Navigation and Design Without Permission: Why I Introduced a No UI Regression Rule
Shiori
While asking AI to add a blog article, I discovered that the navigation layout had also been changed without instruction. This article describes why that happened and how I addressed it with a rule in CLAUDE.md.
Spec First: Why Writing a Specification Before Asking AI to Implement Leads to More Consistent Results
Shiori
Writing a specification before asking AI to implement reduces mismatches and repeated revisions. This article explains the Spec First principle and what to include in a simple specification.
The Next Step After Vibe Coding: What It Takes to Move from Building to Sustaining a Site
Shiori
A record of the new problems that emerged once the Vibe Coding build phase ended and maintenance began, and the harness, tests, and validation I introduced to address them.
The Return on Investment of Harness Engineering: How Investing in Configuration Files Reduced Workload
Shiori
Is the time spent building CLAUDE.md and rule files really necessary? This article explains concretely what changed before and after setting up a harness, based on my own experience.
Verifying Internal Links Against Published URLs: Why Checking File Existence Alone Was Not Enough
Shiori
A file exists in the repository but the link is broken — this happened on this site. Here is why verifying internal links by file path alone is insufficient, and how I addressed it.
What Is Harness Drift: Detecting and Preventing Gaps Between AI Configuration and Code
Shiori
Drift — where configuration files and actual code gradually diverge over time — is a common problem in AI-assisted projects. This article explains the causes and prevention strategies.
What Is Harness Engineering: A Design Approach for Using AI Consistently in Projects
Shiori
AI gives different answers to the same question, and it does not remember previous sessions. This article explains Harness Engineering, a design approach developed to address these challenges when using AI in ongoing projects.