docs: clarify AGENTS.md filtering

privatenumber · privatenumber · commit 759c3aa2ea0c · 2026-01-28T22:54:29.000+09:00
Signed-off-by: Hiroki Osame &lt;hiroki.osame@gmail.com&gt;
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/src/agents/claude.rs b/src/agents/claude.rs
@@ -71,8 +71,7 @@ impl AgentRuleGenerator for ClaudeGenerator {
                 if let Ok(skill_files) = claude_skills::generate_skills_for_optional_rules(
                     &filtered_source_files,
                     current_dir,
-                )
-                {
+                ) {
                     all_files.extend(skill_files);
                 }
             }
@@ -281,10 +280,8 @@ mod tests {
         assert!(
             claude_content.contains("@ai-rules/.generated-ai-rules/ai-rules-generated-always1.md")
         );
-        assert!(
-            claude_content
-                .contains("@ai-rules/.generated-ai-rules/ai-rules-generated-optional-claude.md")
-        );
+        assert!(claude_content
+            .contains("@ai-rules/.generated-ai-rules/ai-rules-generated-optional-claude.md"));
     }
 
     #[test]
diff --git a/src/agents/single_file_based.rs b/src/agents/single_file_based.rs
@@ -190,13 +190,12 @@ mod tests {
             ),
         ];
 
-        let result =
-            generate_agent_file_contents(
-                &source_files,
-                temp_dir.path(),
-                "CLAUDE.md",
-                AGENTS_MD_GROUP_NAME,
-            );
+        let result = generate_agent_file_contents(
+            &source_files,
+            temp_dir.path(),
+            "CLAUDE.md",
+            AGENTS_MD_GROUP_NAME,
+        );
 
         assert_eq!(result.len(), 1);
         let expected_path = temp_dir.path().join("CLAUDE.md");
@@ -229,13 +228,12 @@ mod tests {
             ),
         ];
 
-        let result =
-            generate_agent_file_contents(
-                &source_files,
-                temp_dir.path(),
-                "CLAUDE.md",
-                AGENTS_MD_GROUP_NAME,
-            );
+        let result = generate_agent_file_contents(
+            &source_files,
+            temp_dir.path(),
+            "CLAUDE.md",
+            AGENTS_MD_GROUP_NAME,
+        );
 
         assert_eq!(result.len(), 1);
         let expected_path = temp_dir.path().join("CLAUDE.md");
@@ -275,13 +273,12 @@ mod tests {
             ),
         ];
 
-        let result =
-            generate_agent_file_contents(
-                &source_files,
-                temp_dir.path(),
-                "CLAUDE.md",
-                AGENTS_MD_GROUP_NAME,
-            );
+        let result = generate_agent_file_contents(
+            &source_files,
+            temp_dir.path(),
+            "CLAUDE.md",
+            AGENTS_MD_GROUP_NAME,
+        );
 
         assert_eq!(result.len(), 1);
         let expected_path = temp_dir.path().join("CLAUDE.md");
@@ -326,14 +323,13 @@ mod tests {
             "rule1 body",
         )];
 
-        let result =
-            check_in_sync(
-                &source_files,
-                temp_dir.path(),
-                "CLAUDE.md",
-                AGENTS_MD_GROUP_NAME,
-            )
-            .unwrap();
+        let result = check_in_sync(
+            &source_files,
+            temp_dir.path(),
+            "CLAUDE.md",
+            AGENTS_MD_GROUP_NAME,
+        )
+        .unwrap();
 
         assert!(!result)
     }
@@ -351,14 +347,13 @@ mod tests {
 
         create_file(temp_dir.path(), "CLAUDE.md", "wrong content");
 
-        let result =
-            check_in_sync(
-                &source_files,
-                temp_dir.path(),
-                "CLAUDE.md",
-                AGENTS_MD_GROUP_NAME,
-            )
-            .unwrap();
+        let result = check_in_sync(
+            &source_files,
+            temp_dir.path(),
+            "CLAUDE.md",
+            AGENTS_MD_GROUP_NAME,
+        )
+        .unwrap();
 
         assert!(!result);
     }
@@ -386,14 +381,13 @@ mod tests {
         let expected_content = "@ai-rules/.generated-ai-rules/ai-rules-generated-always1.md\n\n@ai-rules/.generated-ai-rules/ai-rules-generated-optional-agents-md.md\n";
         create_file(temp_dir.path(), "CLAUDE.md", expected_content);
 
-        let result =
-            check_in_sync(
-                &source_files,
-                temp_dir.path(),
-                "CLAUDE.md",
-                AGENTS_MD_GROUP_NAME,
-            )
-            .unwrap();
+        let result = check_in_sync(
+            &source_files,
+            temp_dir.path(),
+            "CLAUDE.md",
+            AGENTS_MD_GROUP_NAME,
+        )
+        .unwrap();
 
         assert!(result);
     }
diff --git a/src/commands/generate.rs b/src/commands/generate.rs
@@ -1,5 +1,7 @@
 use crate::agents::AgentToolRegistry;
 use crate::cli::ResolvedGenerateArgs;
+use crate::constants::AGENTS_MD_AGENTS;
+use crate::models::source_file::warn_on_partial_group_rules;
 use crate::operations::source_reader::detect_symlink_mode;
 use crate::operations::{self, GenerationResult};
 use crate::utils::file_utils::{traverse_project_directories, write_directory_files};
@@ -137,6 +139,12 @@ fn collect_all_files_for_directory(
     let mut files_by_agent: HashMap<String, Vec<PathBuf>> = HashMap::new();
 
     if !source_files.is_empty() {
+        let has_agents_md_group = agents
+            .iter()
+            .any(|agent| AGENTS_MD_AGENTS.iter().any(|name| name == &agent.as_str()));
+        if has_agents_md_group {
+            warn_on_partial_group_rules(&source_files, &AGENTS_MD_AGENTS, "AGENTS.md");
+        }
         let body_files = operations::generate_body_contents(&source_files, current_dir);
         directory_files_to_write.extend(body_files);
         let optional_files =
@@ -344,16 +352,8 @@ blockedAgents: [goose]
 Not for goose optional rule
 "#;
 
-        create_file(
-            temp_dir.path(),
-            "ai-rules/claude-only.md",
-            claude_only_rule,
-        );
-        create_file(
-            temp_dir.path(),
-            "ai-rules/not-goose.md",
-            no_goose_rule,
-        );
+        create_file(temp_dir.path(), "ai-rules/claude-only.md", claude_only_rule);
+        create_file(temp_dir.path(), "ai-rules/not-goose.md", no_goose_rule);
 
         let args = ResolvedGenerateArgs {
             agents: Some(vec!["claude".to_string(), "goose".to_string()]),
diff --git a/src/commands/mod.rs b/src/commands/mod.rs
@@ -98,7 +98,8 @@ mod tests {
         let out_of_sync_agents: Vec<_> = status_result
             .agent_statuses
             .iter()
-            .filter_map(|(agent, in_sync)| (!in_sync).then(|| agent.clone()))
+            .filter(|(_, in_sync)| !**in_sync)
+            .map(|(agent, _)| agent.clone())
             .collect();
         assert!(
             out_of_sync_agents.is_empty(),
diff --git a/src/constants.rs b/src/constants.rs
@@ -4,13 +4,7 @@ pub const GENERATED_RULE_BODY_DIR: &str = ".generated-ai-rules";
 pub const AGENTS_MD_FILENAME: &str = "AGENTS.md";
 pub const AGENTS_MD_GROUP_NAME: &str = "agents-md";
 pub const AGENTS_MD_AGENTS: [&str; 7] = [
-    "amp",
-    "cline",
-    "codex",
-    "copilot",
-    "goose",
-    "kilocode",
-    "roo",
+    "amp", "cline", "codex", "copilot", "goose", "kilocode", "roo",
 ];
 pub const AI_RULE_CONFIG_FILENAME: &str = "ai-rules-config.yaml";
 pub const GENERATED_FILE_PREFIX: &str = "ai-rules-generated-";
diff --git a/src/models/source_file.rs b/src/models/source_file.rs
@@ -114,7 +114,6 @@ impl SourceFile {
         true
     }
 
-
     pub fn from_file<P: AsRef<Path>>(file_path: P) -> Result<Self> {
         let path = file_path.as_ref();
         let content = std::fs::read_to_string(path)
@@ -232,6 +231,35 @@ pub fn filter_source_files_for_agent_group(
         .collect()
 }
 
+pub fn warn_on_partial_group_rules(
+    source_files: &[SourceFile],
+    agent_names: &[&str],
+    group_label: &str,
+) {
+    for source_file in source_files {
+        if source_file.applies_to_agents(agent_names) {
+            continue;
+        }
+
+        let applies_to_any = agent_names
+            .iter()
+            .any(|agent| source_file.applies_to_agent(agent));
+        if !applies_to_any {
+            continue;
+        }
+
+        let identifier = if source_file.base_file_name.is_empty() {
+            source_file.front_matter.description.as_str()
+        } else {
+            source_file.base_file_name.as_str()
+        };
+        eprintln!(
+            "Warning: Rule '{}' applies to a subset of {} agents; it will be excluded from {}.",
+            identifier, group_label, group_label
+        );
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/src/operations/body_generator.rs b/src/operations/body_generator.rs
@@ -108,10 +108,8 @@ pub fn generate_optional_rule_files_for_agents(
         if AGENTS_MD_AGENTS.iter().any(|name| name == &agent.as_str()) {
             continue;
         }
-        let filtered_source_files = crate::models::source_file::filter_source_files_for_agent(
-            source_files,
-            agent,
-        );
+        let filtered_source_files =
+            crate::models::source_file::filter_source_files_for_agent(source_files, agent);
         let optional_content = generate_optional_rules_content(&filtered_source_files);
         if optional_content.is_empty() {
             continue;
@@ -161,12 +159,10 @@ mod tests {
                 description: description.to_string(),
                 always_apply,
                 file_matching_patterns: None,
-                allowed_agents: allowed_agents.map(|agents| {
-                    agents.into_iter().map(|agent| agent.to_string()).collect()
-                }),
-                blocked_agents: blocked_agents.map(|agents| {
-                    agents.into_iter().map(|agent| agent.to_string()).collect()
-                }),
+                allowed_agents: allowed_agents
+                    .map(|agents| agents.into_iter().map(|agent| agent.to_string()).collect()),
+                blocked_agents: blocked_agents
+                    .map(|agents| agents.into_iter().map(|agent| agent.to_string()).collect()),
             },
             body: body.to_string(),
             base_file_name: base_file_name.to_string(),
