Refine proposal document: add path-specific rules and examples for monorepo support

完善提案文档，增加对单体仓库支持的路径特定规则和示例
2025-10-07 06:45:14 +08:00 · 2025-09-29 17:38:43 +00:00
parent da0d5bc188
commit 8792532b09
2 changed files with 165 additions and 11 deletions
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@ Create a unified standard for AI code editor prompt configuration files to addre
 2. **Configuration Synchronization Difficulties**: Team members using different editors need to maintain multiple copies of the same content
 3. **Version Control Conflicts**: Configuration files from different editors need to be separately added to `.gitignore`
 4. **High Migration Costs**: Switching editors requires reconfiguring prompts
+5. **Monorepo Challenges**: Different projects within a monorepo require different prompt configurations

 ## Proposed Standard

@@ -25,15 +26,50 @@ Create a unified standard for AI code editor prompt configuration files to addre
 ```
 .prompt/
  ├─ rules/
-  │  ├─ project[.<editor-identifer>].md     # Project-level prompts (primary file)
-  │  ├─ context[.<editor-identifer>].md     # Context rules (optional)
-  │  └─ code_style[.<editor-identifer>].md  # Code style guidelines (optional)
+  │  ├─ project[/[<custom-filename>]][.<editor-identifer>].md     # Project-level prompts (primary file)
+  │  ├─ context[/[<custom-filename>]][.<editor-identifer>].md     # Context rules (optional)
+  │  └─ code_style[/[<custom-filename>]][.<editor-identifer>].md  # Code style guidelines (optional)
  ├─ config.json                            # Configuration file
  └─ README.md                              # Documentation (optional)
 ```

 The `[.<editor-identifer>]` indicates editor-specific configurations. When omitted, it represents globally shared prompt files.

+### Monorepo Support with Path-Specific Rules
+
+For monorepo projects, configure path-specific rules using glob patterns in `.prompt-config.yaml`:
+
+```yaml
+version: 1.0
+
+prompt:
+  rules:
+    - scope: "packages/frontend/**"  # Frontend packages
+      files:
+        - .prompt/frontend-rules.md
+        - docs/frontend/ai-context.md
+
+    - scope: "packages/backend/**"   # Backend packages
+      files:
+        - .prompt/backend-rules.md
+        - "!docs/frontend/**"  # Exclude frontend docs
+
+    - scope: "**/legacy/**"          # Any legacy directory
+      files:
+        - .prompt/legacy-overrides.md
+
+  default:  # Default rules for unmatched paths
+    files:
+      - .prompt/general.md
+      - docs/ai-guidelines.md
+```
+
+#### Rules Evaluation
+1. **Specificity**: Exact paths > wildcard patterns > default rules
+2. **Exclusion**: Negative patterns (`!path`) exclude files
+3. **Proximity**: Closest `.promptconfig.yaml` wins in nested configurations
+4. **Merge**: Arrays are merged, objects are deep-merged
+
 ### Configuration Examples

 **Basic Configuration:**
@@ -81,6 +117,7 @@ For the VSCode editor, in this example, the following markdown files will be loa
 2. **Editor-Specific Files**: `.prompt/rules/project.{editor}.md` (loaded by specific editors)
 3. **Directory Structure**: Supports subdirectory organization, with `index.md` as the directory entry file
 4. **Merge Strategy**: Content from all matching files will be merged, with editor-specific configurations extending global configurations
+5. **Path-Specific Rules**: For monorepos, uses glob patterns to apply different prompts to different paths

 ## Configuration File Format (`.prompt/config.json`)

@@ -171,7 +208,25 @@ Encourage editor vendors to natively support standard paths:
    "context.md",
    "context.vscode.md"
  ],
-  "aiPrompts.mergeStrategy": "smart"
+  "aiPrompts.mergeStrategy": "smart",
+  "aiPrompts.scopeAware": true, // Enable monorepo path-aware loading
+  "aiPrompts.debug": false // Show debug info about loaded prompts
+}
+```
+
+### Editor Implementation Example
+
+```javascript
+// Pseudocode for scope matching
+function getApplicablePrompts(filePath, config) {
+  const rules = config.rules.filter(rule =>
+    micromatch.isMatch(filePath, rule.scope)
+  );
+
+  // Sort by specificity (more specific patterns first)
+  rules.sort((a, b) => compareSpecificity(a.scope, b.scope));
+
+  return rules.flatMap(rule => rule.files);
 }
 ```

@@ -181,6 +236,7 @@ Encourage editor vendors to natively support standard paths:
   - Configuration validation tool: `prompt-validator`
   - File merging tool: `prompt-merger`
   - Migration assistance tool: `prompt-migrate`
+   - Scope debug tool: `prompt-debug` (shows which prompts apply to which paths)

 2. **Editor Plugins**:
   - VSCode extension: `vscode-prompt-config-integration`
@@ -189,6 +245,7 @@ Encourage editor vendors to natively support standard paths:
 3. **Template Library**:
   - Configuration templates for common project types
   - Best practice examples for various languages
+   - Monorepo configuration examples

 ## Detailed Configuration Specifications

@@ -311,6 +368,9 @@ prompt-validate --generate-report

 # Check editor compatibility
 prompt-validate --check-editor vscode cursor
+
+# Debug path matching (for monorepos)
+prompt-debug --path packages/frontend/src/index.js
 ```

 ## Benefits Analysis
@@ -320,6 +380,7 @@ prompt-validate --check-editor vscode cursor
 - ✅ **Maintainability**: Centralized management, single source of truth
 - ✅ **Flexibility**: Support for global configurations and editor-specific extensions
 - ✅ **Collaboration**: Standardized team configurations, easy sharing
+- ✅ **Monorepo Support**: Path-specific rules for different projects in a monorepo

 ### For Editor Vendors
 - ✅ **Interoperability**: Reduce user migration costs, increase user retention
@@ -334,18 +395,21 @@ prompt-validate --check-editor vscode cursor
 - [ ] Develop configuration validation tool: `@prompt-standard/validator`
 - [ ] Write detailed documentation and examples
 - [ ] Establish community discussion groups (Discord/GitHub Discussions)
+- [ ] Add monorepo path-matching support to core library

 ### Short-term Goals (1-3 months)
 - [ ] Gain support from 2-3 mainstream editors
 - [ ] Create configuration templates for popular projects
 - [ ] Develop IDE plugin prototypes
 - [ ] Establish automated testing processes
+- [ ] Add monorepo examples and best practices

 ### Long-term Vision (6-12 months)
 - [ ] Become a de facto standard, natively supported by multiple editors
 - [ ] Establish certification programs and compatibility testing
 - [ ] Extend support to more AI development tools
 - [ ] Develop graphical configuration management tools
+- [ ] Advanced monorepo support with inheritance and override rules

 ## Technical Support

@@ -359,6 +423,9 @@ npm install -g @prompt-standard/validator

 # Migration tool installation
 npm install -g @prompt-standard/migrate
+
+# Debug tool installation
+npm install -g @prompt-standard/debug
 ```

 ### API Examples
@@ -371,6 +438,9 @@ const prompts = await loader.loadForEditor('vscode')

 const validator = new PromptValidator()
 const results = await validator.validate(prompts)
+
+// For monorepo path-aware loading
+const pathSpecificPrompts = await loader.loadForPath('packages/frontend/src/index.js', 'vscode')
 ```

 ## Call for Participation
@@ -381,26 +451,33 @@ We invite participation from:
 - Implement native standard support
 - Provide feedback and improvement suggestions
 - Participate in standard specification development
+- Add monorepo path-aware prompt loading

 ### For Open Source Projects
 - Adopt standard configurations early
 - Contribute project configuration templates
 - Share usage experiences and best practices
+- Provide monorepo use cases

 ### For Community Members
 - Test and report issues
 - Participate in documentation writing and translation
 - Develop auxiliary tools and plugins
+- Contribute to monorepo support features

 ### For Enterprise Users
 - Provide real business requirements
 - Share enterprise-level application scenarios
 - Participate in standard promotion and implementation
+- Contribute large-scale monorepo requirements

 **Participation Methods**:
 - 📝 Submit Issues and Feature Requests
 - 🔄 Submit Pull Requests
 - 💬 Join community discussions
 - 🚀 Share your configuration examples
+- 🏗️ Contribute monorepo solutions

 **GitHub Repository**: https://github.com/aicode-standard/prompt-config
+
+Join the discussion in [GitHub Issues](https://github.com/aicode-standard/prompt-config/issues)!
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -17,22 +17,58 @@
 2. **配置同步困难**：团队成员使用不同编辑器时需要维护多份相同内容
 3. **版本控制冲突**：不同编辑器的配置文件需要分别添加到 `.gitignore`
 4. **迁移成本高**：切换编辑器时需要重新配置提示词
+5. **单体仓库挑战**：单体仓库中的不同项目需要不同的提示词配置

-## Proposed 标准
+## 提案标准

 ### 核心标准路径

 ```
 .prompt/
  ├─ rules/
-  │  ├─ project[.<editor-identifer>].md     # 项目级提示词（主要文件）
-  │  ├─ context[.<editor-identifer>].md     # 上下文规则（可选）
-  │  └─ code_style[.<editor-identifer>].md  # 代码风格规范（可选）
+  │  ├─ project[/[<自定义文件名>]][.<编辑器标识>].md     # 项目级提示词（主要文件）
+  │  ├─ context[/[<自定义文件名>]][.<编辑器标识>].md     # 上下文规则（可选）
+  │  └─ code_style[/[<自定义文件名>]][.<编辑器标识>].md  # 代码风格规范（可选）
  ├─ config.json                            # 配置文件
  └─ README.md                              # 说明文档（可选）
 ```

-其中，`[.<editor-identifer>]` 是编辑器特定配置。不添加则是全局使用的公共提示词文件。
+其中，`[.<编辑器标识>]` 是编辑器特定配置。不添加则是全局使用的公共提示词文件。
+
+### 单体仓库支持与路径特定规则
+
+对于单体仓库项目，使用 `.prompt-config.yaml` 中的 glob 模式配置路径特定规则：
+
+```yaml
+version: 1.0
+
+prompt:
+  rules:
+    - scope: "packages/frontend/**"  # 前端包
+      files:
+        - .prompt/frontend-rules.md
+        - docs/frontend/ai-context.md
+
+    - scope: "packages/backend/**"   # 后端包
+      files:
+        - .prompt/backend-rules.md
+        - "!docs/frontend/**"  # 排除前端文档
+
+    - scope: "**/legacy/**"          # 任何遗留目录
+      files:
+        - .prompt/legacy-overrides.md
+
+  default:  # 未匹配路径的默认规则
+    files:
+      - .prompt/general.md
+      - docs/ai-guidelines.md
+```
+
+#### 规则评估
+1. **特异性**：精确路径 > 通配符模式 > 默认规则
+2. **排除**：否定模式（`!路径`）排除文件
+3. **就近原则**：嵌套配置中最接近的 `.promptconfig.yaml` 生效
+4. **合并**：数组会合并，对象会深度合并

 ### 配置示例

@@ -51,7 +87,7 @@

 **高级配置（多文件结构）：**

-当提示词内容较多，需要拆分成多个文件时，可以创建对应目录，将提示词按照自定义目录结构进行分类。同样的，也以 `[.<editor-identifer>].md` 结尾。所有的文件都是可选的。
+当提示词内容较多，需要拆分成多个文件时，可以创建对应目录，将提示词按照自定义目录结构进行分类。同样的，也以 `[.<编辑器标识>].md` 结尾。所有的文件都是可选的。

 ```
 .prompt/
@@ -81,6 +117,7 @@
 2. **编辑器特定文件**：`.prompt/rules/project.{editor}.md`（按编辑器加载）
 3. **目录结构**：支持子目录组织，`index.md` 作为目录入口文件
 4. **合并策略**：所有匹配的文件内容会被合并，编辑器特定配置会扩展全局配置
+5. **路径特定规则**：对于单体仓库，使用 glob 模式为不同路径应用不同的提示词

 ## 配置文件格式 (`.prompt/config.json`)

@@ -171,7 +208,25 @@ fi
    "context.md",
    "context.vscode.md"
  ],
-  "aiPrompts.mergeStrategy": "smart"
+  "aiPrompts.mergeStrategy": "smart",
+  "aiPrompts.scopeAware": true, // 启用单体仓库路径感知加载
+  "aiPrompts.debug": false // 显示已加载提示词的调试信息
+}
+```
+
+### 编辑器实现示例
+
+```javascript
+// 范围匹配的伪代码
+function getApplicablePrompts(filePath, config) {
+  const rules = config.rules.filter(rule =>
+    micromatch.isMatch(filePath, rule.scope)
+  );
+
+  // 按特异性排序（更具体的模式优先）
+  rules.sort((a, b) => compareSpecificity(a.scope, b.scope));
+
+  return rules.flatMap(rule => rule.files);
 }
 ```

@@ -181,6 +236,7 @@ fi
   - 配置验证工具：`prompt-validator`
   - 文件合并工具：`prompt-merger`
   - 迁移辅助工具：`prompt-migrate`
+   - 范围调试工具：`prompt-debug`（显示哪些提示词应用于哪些路径）

 2. **编辑器插件**：
   - VSCode 扩展：`vscode-prompt-config-integration`
@@ -189,6 +245,7 @@ fi
 3. **模板库**：
   - 常见项目类型的配置模板
   - 各语言的最佳实践示例
+   - 单体仓库配置示例

 ## 配置文件详细规范

@@ -311,6 +368,9 @@ prompt-validate --generate-report

 # 检查编辑器兼容性
 prompt-validate --check-editor vscode cursor
+
+# 调试路径匹配（用于单体仓库）
+prompt-debug --path packages/frontend/src/index.js
 ```

 ## 收益分析
@@ -320,6 +380,7 @@ prompt-validate --check-editor vscode cursor
 - ✅ **可维护性**：集中管理，单一事实来源
 - ✅ **灵活性**：支持全局配置和编辑器特定扩展
 - ✅ **协作性**：团队配置标准化，易于共享
+- ✅ **单体仓库支持**：为单体仓库中的不同项目提供路径特定规则

 ### 对编辑器厂商
 - ✅ **互操作性**：降低用户迁移成本，提高用户粘性
@@ -334,18 +395,21 @@ prompt-validate --check-editor vscode cursor
 - [ ] 开发配置验证工具：`@prompt-standard/validator`
 - [ ] 编写详细文档和示例
 - [ ] 建立社区讨论组（Discord/GitHub Discussions）
+- [ ] 为核心库添加单体仓库路径匹配支持

 ### 短期目标（1-3月）
 - [ ] 争取 2-3 个主流编辑器支持
 - [ ] 创建流行项目的配置模板
 - [ ] 开发 IDE 插件原型
 - [ ] 建立自动化测试流程
+- [ ] 添加单体仓库示例和最佳实践

 ### 长期愿景（6-12月）
 - [ ] 成为事实标准，被多个编辑器原生支持
 - [ ] 建立认证程序和兼容性测试
 - [ ] 扩展支持更多 AI 开发工具
 - [ ] 开发图形化配置管理工具
+- [ ] 具有继承和覆盖规则的高级单体仓库支持

 ## 技术支持

@@ -359,6 +423,9 @@ npm install -g @prompt-standard/validator

 # 迁移工具安装
 npm install -g @prompt-standard/migrate
+
+# 调试工具安装
+npm install -g @prompt-standard/debug
 ```

 ### API 示例
@@ -371,6 +438,9 @@ const prompts = await loader.loadForEditor('vscode')

 const validator = new PromptValidator()
 const results = await validator.validate(prompts)
+
+// 用于单体仓库路径感知加载
+const pathSpecificPrompts = await loader.loadForPath('packages/frontend/src/index.js', 'vscode')
 ```

 ## 呼吁参与
@@ -381,26 +451,33 @@ const results = await validator.validate(prompts)
 - 实现原生标准支持
 - 提供反馈和改进建议
 - 参与标准规范的制定
+- 添加单体仓库路径感知提示词加载功能

 ### 对于开源项目
 - 率先采用标准配置
 - 贡献项目配置模板
 - 分享使用经验和最佳实践
+- 提供单体仓库用例

 ### 对于社区成员
 - 测试和报告问题
 - 参与文档编写和翻译
 - 开发辅助工具和插件
+- 贡献单体仓库支持功能

 ### 对于企业用户
 - 提供实际业务需求
 - 分享企业级应用场景
 - 参与标准推广和实施
+- 贡献大规模单体仓库需求

 **参与方式**：
 - 📝 提交 Issue 和 Feature Request
 - 🔄 提交 Pull Request
 - 💬 加入社区讨论
 - 🚀 分享你的配置案例
+- 🏗️ 贡献单体仓库解决方案

 **GitHub 仓库**: https://github.com/aicode-standard/prompt-config
+
+加入 https://github.com/aicode-standard/prompt-config/issues 的讨论！