How securecodewarrior/ai-security-rules works
What this project is (type + purpose)
This repo is not an application runtime (no services, no binaries, no deployable code). It’s a rule-pack / documentation repository that publishes security instruction files intended to be copied into other repositories so that AI coding assistants (Copilot, Cursor, Windsurf, Cline, Roo, Aider) produce safer, more compliant code.
• A content source-of-truth (this repo)
• Distribution / installation into target codebases
• Consumption by AI assistants inside developer tools
• Resulting influence on code generation + review loops
This is essentially an “AI SDLC guardrails” architecture.
File tree analysis (what to represent)
Top-level artifacts:
• README.md — explains what rules are, why they exist, and how to install them per tool.
• backend.md — platform rule set (server-side)
• frontend.md — platform rule set (client-side)
• mobile.md — platform rule set (mobile apps)
• language-specific/
• python.md — language rule set for Python
• javascript.md — language rule set for JavaScript
• assets/ — marketing/visuals (banner), not part of functional architecture but can appear as “documentation assets”.
Architecturally, the repo is organized as rule modules by domain:
• Platform-specific modules (backend/frontend/mobile)
• Language-specific modules (python/javascript)
What the README implies about runtime interactions
• Rules are copied into a target project repository in a tool-specific path:
• Copilot: .github/copilot-instructions.md
• Cursor: .cursor/rules
• Windsurf: .windsurfrules
• Cline: .clinerules
• Roo: .roorules
• Aider: CONVENTIONS.md + referenced from .aider.conf.yml
• Tools can apply rules always or conditionally based on metadata (important for showing “rule selection / triggering”).
So the “system” is a pipeline of influence:
SCW Rules Repo → (copy/install) → Target Codebase → AI Tool reads rules → AI generates code under constraints → Developers review/commit → Feedback leads to rule updates (new versions).
AI Coding Assistants (Copilot/Cursor/Windsurf/Cline/Roo/Aider)
5) (Optional but realistic) AI Model/Provider behind the assistant (e.g., hosted LLM) — not in the repo, but relevant to show where prompts go.
6) SDLC Controls (code review, CI, SAST) — also not in this repo, but important to show the “guardrail sits alongside other controls” relationship.
Level 2: Containers (inside the “Rules Repo”)
Break the repo into modules:
• Platform Rules:
• backend.md
• frontend.md
• mobile.md
• Language Rules:
• language-specific/python.md
• language-specific/javascript.md
• Documentation & Assets:
• README.md
• assets/
Level 2: Containers (inside the “Target Project”)
“rule installation targets” as containers/paths:
• .github/copilot-instructions.md
• .cursor/rules
• .windsurfrules
• .clinerules
• .roorules
• CONVENTIONS.md + .aider.conf.yml
This is critical: for this project, file placement is the integration mechanism.
Copy/Adopt flow (human-mediated)
• Developer → copies selected SCW rule file(s) → Target Project specific location
• Notes: “manual copy” or “automated via internal template / repo bootstrap” (if your org does that).
Rule ingestion (tool behavior)
• AI Assistant (inside IDE/editor) → reads rules from repo paths → uses them as system/developer instructions
• Optional: include “metadata triggers” as a decision diamond: “apply always?” / “apply conditionally?”
Prompt + context assembly
• AI Assistant → sends prompt (code context + rules) → LLM provider/service → returns suggestion
Output application
• Developer → accepts/modifies suggestion → commits code
• Code review/CI may catch issues; add a feedback loop: “If recurring violations, update rules.”
Rules evolution
• Findings/feedback from devs/security → updates to SCW rules repo → version bump (repo currently at 1.2.0)
Architectural patterns/design principles to call out
• Policy-as-code / Guidance-as-code: rules are textual artifacts that behave like policy inputs to tools.
• Modular rule composition: choose backend + language-specific, etc.
• Tool adapter pattern: same conceptual rules mapped into different tool-specific file locations/formats.
• Shift-left security enablement: rules apply at authoring time, earlier than CI scanning.
Even though there’s no runtime framework, include:
• AI tools: GitHub Copilot, Cursor, Windsurf, Cline, Roo, Aider
• Integration points: file-based configuration paths listed above
• (Optional) LLM provider node (generic “LLM API/Service”)
Don’t overthink it: “separate into as many components as possible”
For *this* project, “more components” primarily means:
• Break rules into their actual files (backend/frontend/mobile/python/javascript)
• Break integrations into actual installation targets (one per tool)
• AI tool as its own node (because behavior differs)
• human workflow nodes (install, configure metadata, accept suggestions, update rules)