modify skill and plugin

2026-05-13 22:27:48 +09:00
parent d414338780
commit 2d59191df2
24 changed files with 2051 additions and 1 deletions
@@ -0,0 +1,115 @@
+# AGENTS.md Quality Criteria
+
+## Scoring Rubric
+
+### 1. Commands and Workflows - 20 points
+
+20 points: all essential commands documented with context.
+
+- Build, test, lint, format, dev, and deploy commands are present when relevant.
+- Development workflow is clear.
+- Common operations and verification expectations are documented.
+
+15 points: most commands present, some missing context.
+
+10 points: basic commands only, little 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.
+- Unusual "why this way" rules explained briefly.
+
+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 or README basics unless Codex specifically needs it.
+
+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 are accurate.
+- Tech stack and architecture are 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 copied and run.
+- Steps are concrete.
+- Paths are real.
+- Verification expectations are clear.
+
+10 points: mostly actionable.
+
+5 points: some vague instructions.
+
+0 points: vague or theoretical.
+
+## Assessment Process
+
+1. Read each instruction file completely.
+2. Cross-reference with the actual codebase.
+3. Check documented commands against package manifests, scripts, and config.
+4. Verify file and directory references.
+5. Score each criterion.
+6. Calculate total and assign grade.
+7. List specific issues.
+8. Propose concrete, concise improvements.
+
+## Red Flags
+
+- Commands that would fail.
+- References to deleted files or folders.
+- Outdated tech versions.
+- Placeholder template content.
+- Generic advice not specific to the project.
+- Duplicate or contradictory guidance across nested instruction files.
+- An `AGENTS.override.md` that accidentally hides a sibling `AGENTS.md`.
@@ -0,0 +1,180 @@
+# AGENTS.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 repo.
+- Current: reflect the actual codebase and active tooling.
+- Scoped: put broad rules at the repo root; put narrow rules in nested `AGENTS.md` or `AGENTS.override.md`.
+
+## Recommended Sections
+
+Use only sections that matter for the project.
+
+### Commands
+
+```markdown
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `<install command>` | Install dependencies |
+| `<dev command>` | Start development server |
+| `<build command>` | Production build |
+| `<test command>` | Run tests |
+| `<lint command>` | Lint or format |
+```
+
+### Architecture
+
+```markdown
+## Architecture
+
+```
+<root>/
+  <dir>/    # <purpose>
+  <dir>/    # <purpose>
+  <dir>/    # <purpose>
+```
+```
+
+### Key Files
+
+```markdown
+## Key Files
+
+- `<path>` - <purpose>
+- `<path>` - <purpose>
+```
+
+### Code Style
+
+```markdown
+## Code Style
+
+- <project-specific convention>
+- <preference over alternative>
+```
+
+### Environment
+
+```markdown
+## Environment
+
+Required:
+- `<VAR_NAME>` - <purpose>
+
+Setup:
+- <setup step>
+```
+
+### Testing
+
+```markdown
+## Testing
+
+- `<test command>` - <what it tests>
+- <testing convention or pattern>
+```
+
+### Gotchas
+
+```markdown
+## Gotchas
+
+- <non-obvious issue, prerequisite, or ordering dependency>
+```
+
+### Workflow
+
+```markdown
+## Workflow
+
+- <when to do X>
+- <preferred approach for Y>
+```
+
+## Minimal Project Root Template
+
+```markdown
+# <Project Name>
+
+<One-line description>
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `<command>` | <description> |
+
+## Architecture
+
+```
+<structure>
+```
+
+## Gotchas
+
+- <gotcha>
+```
+
+## Comprehensive Project Root Template
+
+```markdown
+# <Project Name>
+
+<One-line description>
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `<command>` | <description> |
+
+## Architecture
+
+```
+<structure with descriptions>
+```
+
+## Key Files
+
+- `<path>` - <purpose>
+
+## Code Style
+
+- <convention>
+
+## Environment
+
+- `<VAR>` - <purpose>
+
+## Testing
+
+- `<command>` - <scope>
+
+## Gotchas
+
+- <gotcha>
+```
+
+## Nested Override Template
+
+Use this for a subdirectory whose rules differ from the repo root.
+
+```markdown
+# <Directory> Instructions
+
+## Scope
+
+- Applies to `<path>/`.
+
+## Local Rules
+
+- <specific rule that differs from root guidance>
+
+## Verification
+
+- `<command>` - <focused check for this directory>
+```
@@ -0,0 +1,131 @@
+# AGENTS.md Update Guidelines
+
+## Core Principle
+
+Only add information that will genuinely help future Codex sessions. The context window is precious; every line must earn its place.
+
+## What To Add
+
+### Commands and Workflows Discovered
+
+```markdown
+## Commands
+
+`npm run build` - Production build.
+`npm run lint` - ESLint check required before handoff.
+```
+
+Why: saves future sessions from rediscovering commands.
+
+### Gotchas and Non-Obvious Patterns
+
+```markdown
+## Gotchas
+
+- Tests must run sequentially because they share a local database.
+- Regenerate API clients with `npm run codegen` after editing OpenAPI files.
+```
+
+Why: prevents repeated debugging.
+
+### Package Relationships
+
+```markdown
+## Architecture
+
+- `packages/api` owns route handlers; `packages/ui` must call it through the shared client.
+```
+
+Why: captures relationships that are not obvious from filenames.
+
+### Testing Approaches That Worked
+
+```markdown
+## Testing
+
+- API endpoint tests use `tests/helpers/request.ts`; avoid ad hoc server setup.
+```
+
+Why: establishes known-good patterns.
+
+### Configuration Quirks
+
+```markdown
+## Environment
+
+- `NEXT_PUBLIC_*` variables must be set at build time.
+```
+
+Why: environment details often waste time when omitted.
+
+## What Not To Add
+
+### Obvious Code Info
+
+Bad:
+
+```markdown
+The `UserService` class handles user operations.
+```
+
+The class name already says that.
+
+### Generic Best Practices
+
+Bad:
+
+```markdown
+Always write tests for new features.
+Use meaningful variable names.
+```
+
+Add only project-specific rules.
+
+### One-Off Fixes
+
+Bad:
+
+```markdown
+We fixed a bug where the login button did not work.
+```
+
+Unless the lesson is durable, leave it out.
+
+### Verbose Explanations
+
+Bad:
+
+```markdown
+The authentication system uses JWT tokens. JWT means JSON Web Token...
+```
+
+Good:
+
+```markdown
+Auth: JWT HS256 tokens in `Authorization: Bearer <token>`.
+```
+
+## Diff Format
+
+For each suggested change:
+
+```markdown
+### Update: ./AGENTS.md
+
+**Why:** The build command exists but was missing from project instructions.
+
+```diff
+## Commands
+
+`npm run build` - Production build.
+```
+```
+
+## Validation Checklist
+
+- Each addition is project-specific.
+- No generic advice or obvious info.
+- Commands are verified against the repo.
+- File paths are accurate.
+- The wording is concise.
+- A new Codex session would benefit from the line.