Taming Agents in the Mercari Web Monorepo

Mercari’s Web team, which has been busy building Mercari’s new Global App, is made up of people from diverse backgrounds – and like them, the tools they use and their setups also differ widely.

As Mercari adopts AI-Native development principles, enabling engineers to leverage these tools without forcing them into a completely different setup has become a goal of utmost importance to help our developers stay productive. So has boosting their productivity with AI-powered tooling that quickly aligns with them, rather than getting in their way.

This is where AGENTS.md comes in: a tool-agnostic AI agent configuration standard that helped us onboard our engineers faster, reducing the amount of boilerplate they need to feed into prompts to create quality outputs, and creating a workflow for automatically updating documentation in the Mercari Web Monorepo.

From Chaos to Clarity

As Mercari enters the AI-Native age, its developers must also learn a variety of models, tools and even new editors or IDEs to channel the capabilities of these new language models. Everyone was empowered to adopt tools of their choosing, and given resources to try out new tech.

While this great freedom allowed us to quickly learn about a broad range of tools, the efficacy of these tools and shape of their output varied greatly, even within teams. As the AI landscape continues to evolve quickly, we didn’t believe the solution was to force everyone to use the same tool, but rather to find a way to align our different work styles toward a shared goal.

When Agents Lack Shared Context

Among the most popular tools in Mercari’s Web Team have been Cursor, with its variety of compatible models, Claude Code, GitHub Copilot, and recently even Codex CLI. Initially, users of Cursor and Claude Code did their best to write rules in the format their respective tools were expecting. Though this worked with some degree of success, work was duplicated among the different maintainers of these rules and there was no process to keep these rules in sync.

This led to these rules slowly but surely diverging from each other, and soon it felt like something had to be done. To make things worse, for those who dared to venture beyond and use other less popular tools, they often had to start every prompting session with the same set of corrections, reminders, and other pleas to the model or tool of their choice. In other words, while the familiarity and knowledge of diverse tools grew within the team, the developer productivity with any one of these tools did not scale particularly well.

This is when we decided to unify these efforts.

Towards AGENTS.md

As a user of Claude Code at that time, I had been growing my CLAUDE.md file incrementally – after each agentic session I asked Claude to summarize all the information it deemed valuable to remember for a future session and append it to our CLAUDE.md file.

While this was working for me, it wasn’t yet bringing much particular value to the team, and we wanted to share this file and my workflow with my team. This is when we first asked ourselves why there wasn’t a standard format that most agentic coding tools would converge towards supporting, and sure enough, we found what at the time was AGENT.md (note the singular number), an RFC proposed by Sourcegraph through its AmpCode project.

We then set out to go through all of our existing Cursor and Claude rules and unite them into a single AGENT.md, which itself linked to smaller markdown files describing different topics like architecture, authentication, or useful commands. CLAUDE.md and many other rules files then simply became symlinks to the main one, but the rest of the team was still wondering about the longevity of this RFC we were intent on following.

OpenAI fortunately later managed to secure the agents.md domain, which was the only thing holding back the standard from using the plural wording – which was also the filename that OpenAI’s own Codex had already been using. With OpenAI’s backing, the standard gained a lot more traction from most of the tools we were using, not least of which Cursor. We therefore adopted the pluralized AGENTS.md standard as our single source of truth.

What we taught our Agents

This AGENTS.md file, though initially quite messy, evolved to become much more organized thanks to the team’s support. Today, it looks something like the following:

# AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

## Build & Test Commands
See @docs/commands.md [(link)](./docs/commands.md)

## Code Style & Standards
See @docs/code-style.md [(link)](./docs/code-style.md)

## Project Architecture
See @docs/architecture.md [(link)](./docs/architecture.md)

## Authentication Patterns
See @docs/authentication.md [(link)](./docs/authentication.md)

## Testing Strategy
See @docs/testing.md [(link)](./docs/testing.md)

In other words, it serves as the entrypoint to many, more topical rules files, such as on the topic of architecture, a crucial topic considering the modular approach our repository follows, as was previously outlined in Gary’s article, without the context of which, the output of most tools ends up having to be completely restructured by the developer, unless carefully prompted with the same initial context every time. The architecture.md file looks something like the following:

# Project Architecture

## Module Structure & Dependencies
- **Monorepo**: Uses pnpm workspaces with clear module boundaries
- **Module types**: `@app/*`, `@feature/*`, `@domain/*`, `@core/*`
- **Dependency flow**: core → domain → feature → app (enforced by eslint-plugin-boundaries)
- **Naming convention**: `@app/globalapp`, `@domain/datalayer`, etc.

## Architectural Layers
- **app modules**: Next.js routing configuration and app-specific setup
- **feature modules**: Business functionality with UI components
- **domain modules**: Shared business logic and data access
- **core modules**: Foundational utilities and framework abstractions

## Key Patterns
- React/Next.js coupling across layers (cache(), server components)
- Domain data services live in `domain/[module]/src/data/`
- Shared infrastructure belongs in core packages; check workspace deps before adding more

Our project also must follow our design system, and cannot rely on simply vibe-coded CSS, therefore we also expressly teach our agents to use the existing components:

## Design System Coding Guideline

### 1. Component Import Standards

- **ALWAYS** import components from `internal-design-system` (not from source files)
- **ALWAYS** import icons from `internal-design-system-icons`
- **NEVER** import directly from component source files
- Use named imports: `import { Button, TextInput, SelectCard } from 'internal-design-system'`

### 2. File Structure Patterns

**For reusable components:**
- Create feature modules in `feature/[feature-name]/` with Storybook stories
- Include `*.stories.tsx` files alongside components for documentation
- Use `src/exports.ts` as the module entry point

**For app-specific pages/components:**
- GlobalOne: Place in `app/globalapp/`
- JP Marketplace: Place in `app/japanapp/`

### 3. Styling Guidelines

- **NEVER** add inline styles on any design system component or native HTML element
- Use design system color tokens (supports light/dark mode automatically)
- For custom styling, use Panda CSS utilities: `css`, `cva`, `sva`
- These functions provide type-safe styles leveraging Panda CSS engine

Other files also go into detail about our custom authentication hooks and different testing patterns. In accumulation, these create a trove of context most models can effectively leverage to significantly improve the quality of their initial outputs, and reduce the amount of back and forth engineers have to engage in to unleash value out of these new tools.

Self-Updating Documentation Loop

While we’re happy with the shape these rules files have taken, as is the challenge with any documentation, they must be kept up to date.

While any edits accompanying a PR are a great and valuable contribution, editing a non-local markdown file in a separate folder, even more than a JSDoc block next to the very function it documents, is often tedious for an engineer focusing on a task.

Unsurprisingly, a tool that makes this task much easier is any large language model. With any PR that has a significant impact on the project’s higher-level design, we encourage the engineer to run an agent against the PR’s changeset and the rules files folder to have the model itself suggest edits to the rules, or point out inconsistencies in the code itself. This workflow effectively gifted us what we had long dreamed of: automatically, self-enforcing and self-updating documentation.

Scaling AI-Native Practices

What we’re now working on is creating an agent to run on every pull request, automatically pointing out code that diverges from these rules, whether it’s been written by a human or a machine, helping us detect bad AI output, train new members faster, and for the cases when a senior engineer does mean to commit a higher-level, more structural change, give them the ability to automatically generate a patch to the relevant rules.

As our Web Team refines this workflow, we aim to share these learnings across Mercari, and hopefully inspire other teams exploring AI-Native development.

Conclusion

In the end, AGENTS.md became more than just a shared rulebook—it became a bridge between people, tools, and ideas. It let every engineer keep their own setup while still moving in the same direction, and every AI assistant contributed with context instead of confusion.

As we keep refining this workflow, our goal remains simple: let humans and agents work side by side, unleashing each other’s capabilities.