Project Settings Markdown Guide: CLAUDE.md and AGENTS.md

What is a Project Settings MD?

Vibe coding tools automatically read specific markdown files in the project root when a session starts. This file serves as a 'rulebook' that the AI must follow in that project.

Settings files by tool:• Claude Code: CLAUDE.md (project root)
• Codex: AGENTS.md (project root)

The filenames differ, but the role and writing style are identical. It's essentially persistent memory that tells the AI agent "work like this in this project."

Why Do You Need It?

Vibe coding is possible without a settings MD. But you'll face the inconvenience of repeating the same instructions every time.

Working without a settings MD:• "Answer in English"
• "Only commit when I tell you to"
• "Don't touch this folder"
• "Ask me before modifying code"

You'd have to repeat these instructions every time you start a new session. They might be forgotten after compaction.

With a settings MD:• Rules are automatically recognized at session start
• Consistent workflow maintained
• Mistake prevention (blocking prohibited actions)
• Same AI behavior guaranteed across team members

Quick Start: The /init Command

If writing from scratch is difficult, use the auto-generation feature. Both tools support the /init command.

Claude Code:

claude
> /init

Codex:

codex
> /init

It analyzes your project structure and tech stack to generate a basic settings file (CLAUDE.md or AGENTS.md). Add the rules you need based on this.

Folder Structure and Priority

Settings MDs can be placed not only in the project root but also in subfolders. Subfolder settings override parent settings.

my-project/
├── CLAUDE.md (or AGENTS.md)  # Project-wide rules
├── frontend/
│   └── CLAUDE.md               # Frontend-specific rules
└── backend/
    └── CLAUDE.md               # Backend-specific rules

Search order:1. Start from the folder containing the current working file
2. Traverse up to parent folders looking for settings files
3. Check up to project root (usually where .git is)
4. Merge all found settings (subfolder takes priority)

Useful for applying different rules to each area in monorepos or multi-project structures.

Global vs Project Settings

There are global settings in your home directory and project settings in the project root.

Claude Code:• Global: ~/.claude/CLAUDE.md → Applies to all projects
• Project: CLAUDE.md in project root → Applies only to that project

Codex:• Global: ~/.codex/AGENTS.md → Applies to all projects
• Project: AGENTS.md in project root → Applies only to that project

It's common to put personal preferences like language and tone in global settings, and project-specific rules in project settings.

Core Components

Here are the main items you can include in a settings MD. Not all are required—just select and write what your project needs.

1. Language & Tone

Define the AI's response language and tone.

## Language
- All explanations in English
- Friendly and natural tone
- Use polite language
- Emojis only when user requests

You can set it to English for global teams, or Japanese for Japanese projects.

2. Work Scope

Specify paths the AI can modify and forbidden paths.

## Work Scope

### Allowed Paths
- `src/` - Source code
- `tests/` - Tests
- `docs/` - Documentation

### No Modifications
- `config/production.json` - Production config
- `.env` - Environment variables
- `dist/` - Build artifacts

Protects sensitive files and build outputs.

3. Code Style

Define the project's coding style.

## Code Conventions

### Style
- Indentation: 2 spaces
- Quotes: single quotes
- Semicolons: omit

### Naming
- Variables/Functions: camelCase
- Classes: PascalCase
- Constants: UPPER_SNAKE_CASE

### Comments
- Write code that explains itself
- Comments explain only 'why'
- Don't add comments to unchanged code

If you have ESLint or Prettier configs, you can specify to follow those settings.

4. Workflow and Prohibitions

The most important part. Define what procedures the AI must follow and what it must never do.

## ⛔ ABSOLUTE PROHIBITIONS

**No unauthorized code modifications**
- ❌ Modify right after analysis
- ✅ Analysis → Propose plan → Approval → Execute

**No unauthorized Git operations**
- ❌ Auto commit, auto push
- ✅ Report changes, execute only on "commit" request

**No unauthorized builds/deployments**
- ❌ "Running build to verify"
- ✅ Only when user explicitly requests

5. Environment Information

Define OS-specific path differences, execution methods, and external tool integrations.

## Environment

### Paths
- macOS: `/Users/dev/project`
- Windows/WSL: `/mnt/c/project`

### Command Execution
- macOS: Execute bash directly
- WSL: Route through PowerShell

### External Tools
- MCP Integration: Unity Editor
- GitHub CLI: `gh workflow run`

6. Git Workflow

Define rules for Git-related operations. Prevent auto commits and pushes, and specify approval procedures.

## Git Workflow

### Read-only (No approval needed)
- `git status`, `git log`, `git diff`, `git branch`

### Approval Required
- `git add`, `git commit`, `git push`, `git pull`
- Execute only on "commit" or "push" request

### Absolutely Forbidden
- `git reset --hard`, `git push --force`
- `git clean -fd` and other destructive commands

### Commit Messages
- Format: `YYYY-MM-DD HH:MM Description`
- No auto signatures

7. Agent Usage

Define sub-agent invocation criteria and parallel processing policies. Claude Code's agent system is already mature, and Codex is introducing an agent system but it's not yet polished.

## Agent Usage

### Sub-agents
- Explore: File search, codebase exploration
- Plan: Complex task planning

### Invocation Criteria
- Search tasks: Explore agent first
- Complex tasks (3+ steps): Plan first

### Parallel Processing
- Explore: Parallel allowed for multi-area exploration
- Git operations: Sequential to prevent conflicts

Using sub-agents well allows you to handle complex tasks while saving main context.

8. Special Notes

Document special rules unique to your project.

## Project Notes

### Build System
- `dist/` is build output → Don't modify directly
- Build: `npm run build`

### Data Files
- JSON uses 2-space indentation
- CSV maintains UTF-8 encoding

### Related Docs
- For API work: See `API.md`
- For deployment: See `DEPLOY.md`

Writing Tips

1. Keep it under 200 lines
Settings MD is included in AI context. Too long means less context for actual work. Codex has a default 32KB limit.

2. Add gradually
Don't try to write perfectly from the start. Add rules whenever the AI makes mistakes.

3. Use code blocks for example commands
Commands in code blocks are followed literally by the AI.

4. Reference other documents
If content gets long, split into separate files and reference them.

For API work → See `API.md`

5. Commit to Git
Settings MD is part of your project. Commit to Git and share with team members. However, add personal settings (settings.local.json, etc.) to .gitignore.

Conclusion

CLAUDE.md and AGENTS.md are 'contracts' with your AI agent. Write them well, and you can expect consistent quality work without repeating the same instructions every time.

Start simple. Every time the AI makes a mistake, think "I should add this rule," and you'll gradually train a smarter agent.