Initial commit

2025-11-30 08:43:17 +08:00
commit 8967d326a7
30 changed files with 5154 additions and 0 deletions
--- a/references/analysis.md
+++ b/references/analysis.md
@@ -0,0 +1,320 @@
+# AGENTS.md Analysis Across 6 Netresearch Projects
+
+## Executive Summary
+
+**Total AGENTS.md Files Found**: 21 files across 6 projects
+
+**Patterns Observed**:
+1. **Root files are thin** (26-348 lines) with precedence rules and global defaults
+2. **Scoped files are focused** on specific subsystems (backend, frontend, CLI, etc.)
+3. **Managed header** present in newer files: `<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: YYYY-MM-DD -->`
+4. **Consistent structure** following the 9-section schema from your prompt
+
+## File Distribution
+
+| Project | Root | Scoped Files | Total Lines (root) |
+|---------|------|--------------|-------------------|
+| t3x-rte_ckeditor_image | ✅ | Classes/, Documentation/, Resources/, Tests/ | 348 |
+| coding_agent_cli_toolset | ✅ | scripts/ | 308 |
+| ldap-selfservice-password-changer | ✅ | internal/, internal/web/ | 282 |
+| ldap-manager | ✅ | cmd/, internal/, internal/web/, scripts/ | 228 |
+| raybeam | ✅ | cmd/, internal/ | 209 |
+| simple-ldap-go | ✅ | docs/, examples/, testutil/ | 26 ⭐ **Perfect thin root** |
+
+## Key Findings
+
+### 1. **simple-ldap-go** is the Best Example ⭐
+
+**Root file** (26 lines):
+- Minimal global rules
+- Clear precedence statement
+- Index of scoped files
+- No duplication with scoped content
+
+```markdown
+## Global rules
+- Keep diffs small; add tests for new code paths
+- Ask first before: adding heavy deps, running full e2e suites, or repo-wide rewrites
+
+## Minimal pre-commit checks
+- Typecheck (all packages): `go build -v ./...`
+- Lint/format (file scope): `gofmt -w <file.go>`
+- Unit tests (fast): `go test -v -race -short -timeout=10s ./...`
+
+## Index of scoped AGENTS.md
+- `./examples/AGENTS.md` — Example applications
+- `./testutil/AGENTS.md` — Testing utilities
+- `./docs/AGENTS.md` — Documentation
+```
+
+### 2. Scoped Files Follow 9-Section Schema
+
+**Example: simple-ldap-go/examples/AGENTS.md**:
+1. ✅ Overview
+2. ✅ Setup & environment  
+3. ✅ Build & tests (file-scoped)
+4. ✅ Code style & conventions
+5. ✅ Security & safety
+6. ✅ PR/commit checklist
+7. ✅ Good vs. bad examples
+8. ✅ When stuck
+9. ⚠️  House Rules (rarely used, only when overriding)
+
+### 3. Managed Header Usage
+
+**Present in** (newer projects):
+- simple-ldap-go (all files)
+- ldap-selfservice-password-changer (all files)
+- raybeam (some files)
+
+**Missing in** (older projects):
+- t3x-rte_ckeditor_image
+- coding_agent_cli_toolset
+
+**Format**:
+```html
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
+```
+
+### 4. Precedence Rules - Consistent Pattern
+
+All root files establish precedence clearly:
+
+**Pattern 1** (verbose):
+> "This file explains repo-wide conventions and where to find scoped rules. **Precedence:** the **closest `AGENTS.md`** to the files you're changing wins. Root holds global defaults only."
+
+**Pattern 2** (concise):
+> "**Precedence**: Nearest AGENTS.md wins. This is the root file with global defaults."
+
+**Pattern 3** (index-focused):
+> "## Precedence & Scoped Files  
+> Nearest AGENTS.md wins. Use this root for defaults only."
+
+### 5. Docker-First vs Native-First
+
+**Docker-first projects** (ldap-selfservice-password-changer, ldap-manager):
+```markdown
+### Setup
+**Prerequisites**: Docker + Docker Compose (required), Go 1.25+, Node.js 24+, pnpm 10.18+ (for native dev)
+
+# Docker (recommended)
+docker compose --profile dev up
+
+# Native development
+pnpm install
+```
+
+**Native-first projects** (simple-ldap-go, t3x-rte_ckeditor_image):
+```markdown
+### Setup
+**Prerequisites**: Go 1.24, golangci-lint
+
+# Install
+go mod download
+```
+
+### 6. Language-Specific Patterns
+
+**Go Projects** (simple-ldap-go, ldap-manager, raybeam):
+- Minimal pre-commit: `go build -v ./...`, `gofmt -w`, `go test -short`
+- Go version in global rules (1.24, 1.25)
+- golangci-lint for comprehensive checks
+
+**PHP Project** (t3x-rte_ckeditor_image):
+- Composer scripts for CI pipeline
+- PHPStan + PHP-CS-Fixer + Rector
+- Make targets preferred over composer commands
+
+**Hybrid Projects** (ldap-selfservice-password-changer):
+- Separate sections for Go backend vs TypeScript frontend
+- Scoped AGENTS.md for `internal/` (Go) and `internal/web/` (TS)
+- pnpm for package management (strict version)
+
+### 7. Quick Start Patterns
+
+**Best practice** (ldap-selfservice-password-changer):
+```markdown
+## Quick Navigation
+- [internal/AGENTS.md](internal/AGENTS.md) - Go backend services
+- [internal/web/AGENTS.md](internal/web/AGENTS.md) - TypeScript frontend
+```
+
+**Alternative** (simple-ldap-go):
+```markdown
+## Index of scoped AGENTS.md
+- `./examples/AGENTS.md` — Example applications and usage patterns
+- `./testutil/AGENTS.md` — Testing utilities and container management
+```
+
+### 8. House Rules Implementation
+
+**Global defaults** typically include:
+- Commits: Conventional Commits, small PRs (~≤300 LOC)
+- Type-safety: Strict types when supported
+- SOLID, KISS, DRY, YAGNI principles
+- SemVer for versioning
+- No secrets in VCS
+- Structured logging
+- WCAG AA for UI projects
+
+**Scoped overrides** (rare):
+- Different test coverage targets per module
+- Module-specific commit conventions
+- Technology-specific style guides
+
+### 9. Common Gaps Across Projects
+
+❌ **Missing .envrc** in most projects (your prompt requires it)
+❌ **Missing .editorconfig** in some projects
+❌ **Husky + commitlint** not universally adopted
+❌ **lint-staged** not implemented in older projects
+❌ **CI parity section** often missing (should reference GitHub Actions)
+
+## Recommendations for Your Skill
+
+### Essential Features
+
+1. **Template Selection**:
+   - Thin root (simple-ldap-go style) ⭐
+   - Verbose root (ldap-selfservice-password-changer style)
+   - Auto-detect based on project size
+
+2. **Project Type Detection**:
+   - Go: Look for `go.mod`, detect version from `go.mod` directive
+   - PHP: Look for `composer.json`, detect TYPO3 from dependencies
+   - TypeScript: Look for `tsconfig.json`, detect strict mode
+   - Hybrid: Detect multiple languages, recommend scoped files
+
+3. **Scoped File Generation**:
+   - **Required scopes**: backend/, frontend/, internal/
+   - **Optional scopes**: cmd/, scripts/, examples/, docs/, testutil/
+   - **Auto-create** if directory exists and has ≥5 files
+
+4. **Content Extraction**:
+   - **Makefile**: Extract targets with `##` comments → Build & Test Commands
+   - **package.json scripts**: Extract npm/pnpm commands
+   - **go.mod**: Extract Go version → Prerequisites
+   - **composer.json scripts**: Extract PHP quality commands
+   - **GitHub Actions**: Extract CI checks → PR/commit checklist
+
+5. **Managed Header**:
+   - Always add to new files
+   - Preserve in existing files
+   - Update timestamp on regeneration
+
+6. **Precedence Rules**:
+   - Auto-add "Nearest AGENTS.md wins" statement
+   - Generate index of scoped files in root
+   - Link from root to scoped files
+
+### Skill Structure Recommendation
+
+```
+agents-skill/
+├── SKILL.md
+├── README.md
+├── templates/
+│   ├── root-thin.md          # simple-ldap-go style (recommended)
+│   ├── root-verbose.md       # ldap-selfservice style
+│   ├── scoped-backend.md     # Go/PHP backend
+│   ├── scoped-frontend.md    # TypeScript/JS frontend
+│   ├── scoped-cli.md         # CLI tools
+│   ├── scoped-docs.md        # Documentation
+│   ├── scoped-tests.md       # Testing utilities
+│   └── sections/             # Modular sections
+│       ├── header.md         # Managed header template
+│       ├── precedence.md     # Precedence statement
+│       ├── setup.md          # Setup section
+│       ├── build-commands.md # Build & test commands
+│       ├── code-style.md     # Code style guidelines
+│       ├── security.md       # Security practices
+│       ├── pr-checklist.md   # PR/commit checklist
+│       ├── examples.md       # Good vs bad examples
+│       └── when-stuck.md     # When stuck guidance
+├── scripts/
+│   ├── generate-agents.sh    # Main generator
+│   ├── detect-project.sh     # Auto-detect project type
+│   ├── extract-commands.sh   # Extract from Makefile/package.json
+│   └── validate-structure.sh # Validate generated files
+└── references/
+    ├── examples/             # Real-world examples
+    │   ├── go-library.md     # simple-ldap-go
+    │   ├── go-web-app.md     # ldap-manager
+    │   ├── php-typo3.md      # t3x-rte_ckeditor_image
+    │   └── hybrid-app.md     # ldap-selfservice-password-changer
+    └── best-practices.md     # AGENTS.md writing guide
+```
+
+### Key Differentiators
+
+✅ **Thin root by default** (not verbose like some projects)
+✅ **Auto-scope detection** (create scoped files when needed)
+✅ **Command extraction** (don't make user write commands manually)
+✅ **Managed header** (mark files as agent-maintained)
+✅ **Language-agnostic** (works with Go, PHP, TypeScript, Python, etc.)
+✅ **Idempotent** (can be re-run without breaking existing structure)
+
+## Sample Output Comparison
+
+### Your Prompt's Expected Output
+
+**Root AGENTS.md** (following simple-ldap-go pattern):
+```markdown
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
+
+# AGENTS.md (root)
+
+**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only.
+
+## Global rules
+- Keep PRs small (~≤300 net LOC)
+- Conventional Commits: type(scope): subject
+- Ask before: heavy deps, full e2e, repo rewrites
+- Never commit secrets or PII
+
+## Minimal pre-commit checks
+- Typecheck: [auto-detected command]
+- Lint: [auto-detected command]
+- Format: [auto-detected command]
+- Tests: [auto-detected command]
+
+## Index of scoped AGENTS.md
+- `./internal/AGENTS.md` — Go backend services
+- `./internal/web/AGENTS.md` — TypeScript frontend
+
+## When instructions conflict
+Nearest AGENTS.md wins. User prompts override files.
+```
+
+**Scoped AGENTS.md** (e.g., internal/AGENTS.md):
+```markdown
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
+
+# AGENTS.md — Backend Services
+
+## Overview
+[Auto-generated description of internal/ directory purpose]
+
+## Setup & environment
+[Auto-detected from go.mod, .env.example]
+
+## Build & tests (prefer file-scoped)
+[Auto-extracted from Makefile, go commands]
+
+## Code style & conventions
+[Auto-detected from golangci-lint config, gofmt]
+
+## Security & safety
+[Standard Go security practices + project-specific]
+
+## PR/commit checklist
+[Auto-extracted from GitHub Actions, Makefile]
+
+## Good vs. bad examples
+[Template with placeholders to fill]
+
+## When stuck
+- Check root AGENTS.md for global rules
+- Review sibling modules for patterns
+```
+