modify template

2026-06-10 17:12:23 +09:00
parent 2d59191df2
commit df3cc3e890
186 changed files with 24935 additions and 2 deletions
@@ -0,0 +1,151 @@
+---
+name: claude-md-improver
+description: Audit and improve project instruction files such as AGENTS.md, CLAUDE.md, .agents.local.md, and .claude.local.md. Use when the user asks to check, audit, update, improve, or fix project memory or instruction files.
+---
+
+# Project Instruction Improver
+
+Audit, evaluate, and improve project instruction files so future Codex or Claude sessions have concise, current, actionable project context.
+
+This skill can write to instruction files only after presenting a quality report and getting user approval.
+
+## Workflow
+
+### Phase 1: Discovery
+
+Find project instruction files in the repository. Prefer `rg --files`; on Windows, use PowerShell-native commands if needed.
+
+```powershell
+rg --files | rg '(^|/)(AGENTS\.md|CLAUDE\.md|\.agents\.local\.md|\.claude\.local\.md)$'
+```
+
+File types and locations:
+
+| Type | Location | Purpose |
+| --- | --- | --- |
+| Codex project root | `./AGENTS.md` | Primary Codex project instructions, usually checked into git |
+| Claude project root | `./CLAUDE.md` | Primary Claude Code project context, usually checked into git |
+| Local Codex override | `./.agents.local.md` | Personal/local Codex notes, normally gitignored |
+| Local Claude override | `./.claude.local.md` | Personal/local Claude notes, normally gitignored |
+| Global Codex defaults | `~/.codex/AGENTS.md` | User-wide Codex defaults |
+| Global Claude defaults | `~/.claude/CLAUDE.md` | User-wide Claude defaults |
+| Nested/package files | `**/AGENTS.md` or `**/CLAUDE.md` | Module-level context in monorepos |
+
+When both `AGENTS.md` and `CLAUDE.md` exist, keep tool-specific rules in the matching file and avoid duplicating generic content unless the user asks for parity.
+
+### Phase 2: Quality Assessment
+
+For each instruction file, evaluate it against [references/quality-criteria.md](references/quality-criteria.md).
+
+Quick checklist:
+
+| Criterion | Weight | Check |
+| --- | --- | --- |
+| Commands/workflows documented | High | Are build/test/lint/deploy commands present and executable? |
+| Architecture clarity | High | Can an agent understand the codebase structure? |
+| Non-obvious patterns | Medium | Are gotchas and project-specific quirks documented? |
+| Conciseness | Medium | Does every line earn its prompt cost? |
+| Currency | High | Does it reflect the current codebase state? |
+| Actionability | High | Are instructions concrete, not vague? |
+
+Quality scores:
+
+- A (90-100): Comprehensive, current, actionable
+- B (70-89): Good coverage, minor gaps
+- C (50-69): Basic info, missing key sections
+- D (30-49): Sparse or outdated
+- F (0-29): Missing or severely outdated
+
+### Phase 3: Quality Report
+
+Always output the quality report before making updates.
+
+```markdown
+## Project Instruction Quality Report
+
+### Summary
+- Files found: X
+- Average score: X/100
+- Files needing update: X
+
+### File-by-File Assessment
+
+#### 1. ./AGENTS.md
+**Score: XX/100 (Grade: X)**
+
+| Criterion | Score | Notes |
+| --- | --- | --- |
+| Commands/workflows | X/20 | ... |
+| Architecture clarity | X/20 | ... |
+| Non-obvious patterns | X/15 | ... |
+| Conciseness | X/15 | ... |
+| Currency | X/15 | ... |
+| Actionability | X/15 | ... |
+
+**Issues:**
+- ...
+
+**Recommended additions:**
+- ...
+```
+
+### Phase 4: Targeted Updates
+
+After the report, ask for confirmation before editing.
+
+Update guidelines:
+
+1. Propose targeted additions only:
+   - Commands or workflows discovered during analysis
+   - Gotchas or non-obvious patterns found in code
+   - Package relationships that were unclear
+   - Testing approaches that work
+   - Environment or configuration quirks
+2. Keep changes minimal:
+   - Do not restate obvious code structure
+   - Do not add generic best practices
+   - Do not preserve one-off fixes unlikely to recur
+   - Prefer one-line notes over long explanations
+3. Show diffs:
+   - File to update
+   - Exact addition or replacement
+   - One-line reason this helps future sessions
+
+Diff format:
+
+````markdown
+### Update: ./AGENTS.md
+
+**Why:** The build command was missing.
+
+```diff
+ ## Commands
+ `npm run build` - Production build.
+```
+````
+
+### Phase 5: Apply Updates
+
+After user approval, edit only the approved instruction files. Preserve existing structure and formatting, and do not change unrelated project files.
+
+## Templates
+
+Use [references/templates.md](references/templates.md) as a source of section patterns, adapting `CLAUDE.md` examples to `AGENTS.md` when working in Codex projects.
+
+## Common Issues to Flag
+
+1. Stale commands that no longer work
+2. Missing dependencies or setup steps
+3. Outdated architecture or deleted paths
+4. Missing environment variables or config notes
+5. Broken test commands
+6. Undocumented gotchas or recurring workflow mistakes
+
+## User Tips
+
+When presenting recommendations, remind users:
+
+- Keep instruction files concise; they become model context.
+- Commands should be copy-paste ready.
+- Store shared team rules in `AGENTS.md` or `CLAUDE.md`.
+- Store personal preferences in local-only files if the project uses them.
@@ -0,0 +1,109 @@
+# CLAUDE.md Quality Criteria
+
+## Scoring Rubric
+
+### 1. Commands/Workflows (20 points)
+
+**20 points**: All essential commands documented with context
+- Build, test, lint, deploy commands present
+- Development workflow clear
+- Common operations documented
+
+**15 points**: Most commands present, some missing context
+
+**10 points**: Basic commands only, no workflow
+
+**5 points**: Few commands, many missing
+
+**0 points**: No commands documented
+
+### 2. Architecture Clarity (20 points)
+
+**20 points**: Clear codebase map
+- Key directories explained
+- Module relationships documented
+- Entry points identified
+- Data flow described where relevant
+
+**15 points**: Good structure overview, minor gaps
+
+**10 points**: Basic directory listing only
+
+**5 points**: Vague or incomplete
+
+**0 points**: No architecture info
+
+### 3. Non-Obvious Patterns (15 points)
+
+**15 points**: Gotchas and quirks captured
+- Known issues documented
+- Workarounds explained
+- Edge cases noted
+- "Why we do it this way" for unusual patterns
+
+**10 points**: Some patterns documented
+
+**5 points**: Minimal pattern documentation
+
+**0 points**: No patterns or gotchas
+
+### 4. Conciseness (15 points)
+
+**15 points**: Dense, valuable content
+- No filler or obvious info
+- Each line adds value
+- No redundancy with code comments
+
+**10 points**: Mostly concise, some padding
+
+**5 points**: Verbose in places
+
+**0 points**: Mostly filler or restates obvious code
+
+### 5. Currency (15 points)
+
+**15 points**: Reflects current codebase
+- Commands work as documented
+- File references accurate
+- Tech stack current
+
+**10 points**: Mostly current, minor staleness
+
+**5 points**: Several outdated references
+
+**0 points**: Severely outdated
+
+### 6. Actionability (15 points)
+
+**15 points**: Instructions are executable
+- Commands can be copy-pasted
+- Steps are concrete
+- Paths are real
+
+**10 points**: Mostly actionable
+
+**5 points**: Some vague instructions
+
+**0 points**: Vague or theoretical
+
+## Assessment Process
+
+1. Read the CLAUDE.md file completely
+2. Cross-reference with actual codebase:
+   - Run documented commands (mentally or actually)
+   - Check if referenced files exist
+   - Verify architecture descriptions
+3. Score each criterion
+4. Calculate total and assign grade
+5. List specific issues found
+6. Propose concrete improvements
+
+## Red Flags
+
+- Commands that would fail (wrong paths, missing deps)
+- References to deleted files/folders
+- Outdated tech versions
+- Copy-paste from templates without customization
+- Generic advice not specific to the project
+- "TODO" items never completed
+- Duplicate info across multiple CLAUDE.md files
@@ -0,0 +1,253 @@
+# CLAUDE.md Templates
+
+## Key Principles
+
+- **Concise**: Dense, human-readable content; one line per concept when possible
+- **Actionable**: Commands should be copy-paste ready
+- **Project-specific**: Document patterns unique to this project, not generic advice
+- **Current**: All info should reflect actual codebase state
+
+---
+
+## Recommended Sections
+
+Use only the sections relevant to the project. Not all sections are needed.
+
+### Commands
+
+Document the essential commands for working with the project.
+
+```markdown
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<install command>` | Install dependencies |
+| `<dev command>` | Start development server |
+| `<build command>` | Production build |
+| `<test command>` | Run tests |
+| `<lint command>` | Lint/format code |
+```
+
+### Architecture
+
+Describe the project structure so Claude understands where things live.
+
+```markdown
+## Architecture
+
+```
+<root>/
+  <dir>/    # <purpose>
+  <dir>/    # <purpose>
+  <dir>/    # <purpose>
+```
+```
+
+### Key Files
+
+List important files that Claude should know about.
+
+```markdown
+## Key Files
+
+- `<path>` - <purpose>
+- `<path>` - <purpose>
+```
+
+### Code Style
+
+Document project-specific coding conventions.
+
+```markdown
+## Code Style
+
+- <convention>
+- <convention>
+- <preference over alternative>
+```
+
+### Environment
+
+Document required environment variables and setup.
+
+```markdown
+## Environment
+
+Required:
+- `<VAR_NAME>` - <purpose>
+- `<VAR_NAME>` - <purpose>
+
+Setup:
+- <setup step>
+```
+
+### Testing
+
+Document testing approach and commands.
+
+```markdown
+## Testing
+
+- `<test command>` - <what it tests>
+- <testing convention or pattern>
+```
+
+### Gotchas
+
+Document non-obvious patterns, quirks, and warnings.
+
+```markdown
+## Gotchas
+
+- <non-obvious thing that causes issues>
+- <ordering dependency or prerequisite>
+- <common mistake to avoid>
+```
+
+### Workflow
+
+Document development workflow patterns.
+
+```markdown
+## Workflow
+
+- <when to do X>
+- <preferred approach for Y>
+```
+
+---
+
+## Template: Project Root (Minimal)
+
+```markdown
+# <Project Name>
+
+<One-line description>
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<command>` | <description> |
+
+## Architecture
+
+```
+<structure>
+```
+
+## Gotchas
+
+- <gotcha>
+```
+
+---
+
+## Template: Project Root (Comprehensive)
+
+```markdown
+# <Project Name>
+
+<One-line description>
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<command>` | <description> |
+
+## Architecture
+
+```
+<structure with descriptions>
+```
+
+## Key Files
+
+- `<path>` - <purpose>
+
+## Code Style
+
+- <convention>
+
+## Environment
+
+- `<VAR>` - <purpose>
+
+## Testing
+
+- `<command>` - <scope>
+
+## Gotchas
+
+- <gotcha>
+```
+
+---
+
+## Template: Package/Module
+
+For packages within a monorepo or distinct modules.
+
+```markdown
+# <Package Name>
+
+<Purpose of this package>
+
+## Usage
+
+```
+<import/usage example>
+```
+
+## Key Exports
+
+- `<export>` - <purpose>
+
+## Dependencies
+
+- `<dependency>` - <why needed>
+
+## Notes
+
+- <important note>
+```
+
+---
+
+## Template: Monorepo Root
+
+```markdown
+# <Monorepo Name>
+
+<Description>
+
+## Packages
+
+| Package | Description | Path |
+|---------|-------------|------|
+| `<name>` | <purpose> | `<path>` |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<command>` | <description> |
+
+## Cross-Package Patterns
+
+- <shared pattern>
+- <generation/sync pattern>
+```
+
+---
+
+## Update Principles
+
+When updating any CLAUDE.md:
+
+1. **Be specific**: Use actual file paths, real commands from this project
+2. **Be current**: Verify info against the actual codebase
+3. **Be brief**: One line per concept when possible
+4. **Be useful**: Would this help a new Claude session understand the project?
@@ -0,0 +1,150 @@
+# CLAUDE.md Update Guidelines
+
+## Core Principle
+
+Only add information that will genuinely help future Claude sessions. The context window is precious - every line must earn its place.
+
+## What TO Add
+
+### 1. Commands/Workflows Discovered
+
+```markdown
+## Build
+
+`npm run build:prod` - Full production build with optimization
+`npm run build:dev` - Fast dev build (no minification)
+```
+
+Why: Saves future sessions from discovering these again.
+
+### 2. Gotchas and Non-Obvious Patterns
+
+```markdown
+## Gotchas
+
+- Tests must run sequentially (`--runInBand`) due to shared DB state
+- `yarn.lock` is authoritative; delete `node_modules` if deps mismatch
+```
+
+Why: Prevents repeating debugging sessions.
+
+### 3. Package Relationships
+
+```markdown
+## Dependencies
+
+The `auth` module depends on `crypto` being initialized first.
+Import order matters in `src/bootstrap.ts`.
+```
+
+Why: Architecture knowledge that isn't obvious from code.
+
+### 4. Testing Approaches That Worked
+
+```markdown
+## Testing
+
+For API endpoints: Use `supertest` with the test helper in `tests/setup.ts`
+Mocking: Factory functions in `tests/factories/` (not inline mocks)
+```
+
+Why: Establishes patterns that work.
+
+### 5. Configuration Quirks
+
+```markdown
+## Config
+
+- `NEXT_PUBLIC_*` vars must be set at build time, not runtime
+- Redis connection requires `?family=0` suffix for IPv6
+```
+
+Why: Environment-specific knowledge.
+
+## What NOT to Add
+
+### 1. Obvious Code Info
+
+Bad:
+```markdown
+The `UserService` class handles user operations.
+```
+
+The class name already tells us this.
+
+### 2. Generic Best Practices
+
+Bad:
+```markdown
+Always write tests for new features.
+Use meaningful variable names.
+```
+
+This is universal advice, not project-specific.
+
+### 3. One-Off Fixes
+
+Bad:
+```markdown
+We fixed a bug in commit abc123 where the login button didn't work.
+```
+
+Won't recur; clutters the file.
+
+### 4. Verbose Explanations
+
+Bad:
+```markdown
+The authentication system uses JWT tokens. JWT (JSON Web Tokens) are
+an open standard (RFC 7519) that defines a compact and self-contained
+way for securely transmitting information between parties as a JSON
+object. In our implementation, we use the HS256 algorithm which...
+```
+
+Good:
+```markdown
+Auth: JWT with HS256, tokens in `Authorization: Bearer <token>` header.
+```
+
+## Diff Format for Updates
+
+For each suggested change:
+
+### 1. Identify the File
+
+```
+File: ./CLAUDE.md
+Section: Commands (new section after ## Architecture)
+```
+
+### 2. Show the Change
+
+```diff
+ ## Architecture
+ ...
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Dev server with HMR |
+| `npm run build` | Production build |
+| `npm test` | Run test suite |
+```
+
+### 3. Explain Why
+
+> **Why this helps:** The build commands weren't documented, causing
+> confusion about how to run the project. This saves future sessions
+> from needing to inspect `package.json`.
+
+## Validation Checklist
+
+Before finalizing an update, verify:
+
+- [ ] Each addition is project-specific
+- [ ] No generic advice or obvious info
+- [ ] Commands are tested and work
+- [ ] File paths are accurate
+- [ ] Would a new Claude session find this helpful?
+- [ ] Is this the most concise way to express the info?
@@ -0,0 +1,72 @@
+---
+name: revise-claude-md
+description: Capture useful learnings from the current session into AGENTS.md, CLAUDE.md, .agents.local.md, or .claude.local.md. Use when the user asks to revise project instructions, update project memory, capture session learnings, or run the Claude /revise-claude-md workflow in Codex.
+---
+
+# Revise Project Instructions
+
+Review the current session for durable learnings about working in this codebase, then propose concise updates to the appropriate project instruction file.
+
+## Step 1: Reflect
+
+Identify context that would help future Codex or Claude sessions:
+
+- Commands that were used or discovered
+- Code style patterns that were followed
+- Testing approaches that worked
+- Environment or configuration quirks
+- Recurring warnings, gotchas, or workflow constraints
+
+Only keep information likely to recur. Do not capture one-off debugging details or generic software engineering advice.
+
+## Step 2: Find Instruction Files
+
+Search for relevant files:
+
+```powershell
+rg --files | rg '(^|/)(AGENTS\.md|CLAUDE\.md|\.agents\.local\.md|\.claude\.local\.md)$'
+```
+
+Choose the target file:
+
+- `AGENTS.md`: Codex project instructions shared with the team
+- `CLAUDE.md`: Claude Code project context shared with the team
+- `.agents.local.md`: personal/local Codex notes, normally gitignored
+- `.claude.local.md`: personal/local Claude notes, normally gitignored
+
+When the repo has `AGENTS.md`, prefer it for Codex-specific rules. When the repo has only `CLAUDE.md`, use `CLAUDE.md` unless the user asks to create an `AGENTS.md`.
+
+## Step 3: Draft Additions
+
+Keep additions concise. One line per concept is usually enough.
+
+Format:
+
+```text
+<command or pattern> - <brief description>
+```
+
+Avoid:
+
+- Verbose explanations
+- Obvious information
+- One-off fixes unlikely to recur
+- Duplicating an existing rule
+
+## Step 4: Show Proposed Changes
+
+For each proposed addition, show:
+
+````markdown
+### Update: ./AGENTS.md
+
+**Why:** <one-line reason>
+
+```diff
+ <the addition>
+```
+````
+
+## Step 5: Apply with Approval
+
+Ask if the user wants to apply the changes. Only edit files they approve, preserve existing structure, and keep the update focused on approved additions.