# Building an AI-Native Coding Project: A Practical Setup Guide for Claude Code and Cursor Modern AI coding agents are much more capable than autocomplete tools. Both **Claude Code** and **Cursor** can understand a repository, modify multiple files, execute commands, run tests, use external tools, delegate work to specialized agents, and perform iterative debugging. The problem is that an AI agent is only as reliable as the **engineering context and guardrails** you give it. A good project therefore needs more than a single instruction file. You want a structure that answers: * What is this project? * What architecture should the AI follow? * How should code be written? * Which rules apply to backend vs frontend? * How should tests be written? * How should security be checked? * Which repetitive workflows should be reusable? * Which tasks deserve specialized agents? * Which actions should be automatically validated or blocked? * Which external systems can the AI access? * How can the same engineering standards be used by multiple AI coding tools? This article builds that system practically for **Claude Code and Cursor**, using a Node.js/TypeScript application as the example. * * * # 1\. The Goal: Turn a Repository into an AI-Native Development Environment A traditional project might look like this: ```text project/ ├── src/ ├── tests/ ├── package.json ├── README.md └── .gitignore ``` The developer knows the architecture because they have worked on it for months. The AI does not. Every new session starts with limited knowledge of your project. Claude Code explicitly describes `CLAUDE.md` as persistent project context, while Cursor provides persistent rules and `AGENTS.md` for the same general purpose. ([Claude](https://code.claude.com/docs/en/memory)) So we introduce an **AI engineering layer**: ```text ┌─────────────────────┐ │ Developer │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ AI Agent │ │ Claude / Cursor │ └──────────┬──────────┘ │ ┌─────────────────────┼─────────────────────┐ │ │ │ ▼ ▼ ▼ Instructions Rules Skills │ │ │ └─────────────────────┼─────────────────────┘ │ ▼ Subagents │ ▼ MCP / Tools │ ▼ Hooks │ ▼ Code + Tests + Validation ``` The important idea is: > **Instructions tell the AI what to do. Rules tell it how to work. Skills teach it repeatable workflows. Subagents specialize the work. Hooks enforce guardrails. MCP gives it external capabilities.** * * * # 2\. Claude Code vs Cursor Architecture Although both tools solve similar problems, their configuration mechanisms are not identical. | Capability | Claude Code | Cursor | | --- | --- | --- | | Main project instructions | `CLAUDE.md` | `AGENTS.md` / Rules | | Project rules | `.claude/rules/*.md` | `.cursor/rules/*.mdc` | | Local personal instructions | `CLAUDE.local.md` | User Rules | | Skills | `.claude/skills/` | `.cursor/skills/` | | Subagents | `.claude/agents/` | `.cursor/agents/` | | Commands | `.claude/commands/` | Commands / Skills | | Hooks | `.claude/settings.json` / hook configuration | `.cursor/hooks.json` | | MCP | `.mcp.json` / settings | `.cursor/mcp.json` | | Auto memory | Yes | Different mechanisms | | Browser/visual workflow | Via available tools | Built into Agent workflows | | Marketplace/plugins | Claude ecosystem | Cursor Marketplace | | Team rules | Managed configuration | Team Rules / Customize | Cursor currently describes Agent as an orchestration of **instructions, tools and a model**, with capabilities including code search, file editing, shell execution and browser interaction. ([Cursor](https://cursor.com/docs/agent/overview?utm_source=chatgpt.com)) Cursor's current Customize system also brings **plugins, skills, MCP, subagents, rules, commands and hooks** together. ([Cursor](https://prod.cursor.com/docs/customize-cursor?utm_source=chatgpt.com)) Claude Code has a comparable modular architecture around `CLAUDE.md`, rules, skills, subagents, hooks and MCP. ([Claude](https://code.claude.com/docs/en/memory)) * * * # 3\. The Recommended Cross-Platform Architecture If you use both tools on the same repository, don't create two completely independent AI configurations. Instead, separate: ### Shared engineering knowledge ```text AGENTS.md docs/ .cursor/rules/ ``` from: ### Claude-specific configuration ```text CLAUDE.md .claude/ ``` and: ### Cursor-specific configuration ```text .cursor/ ``` A practical project can therefore look like: ```text my-project/ │ ├── AGENTS.md ├── CLAUDE.md │ ├── src/ ├── tests/ ├── docs/ │ ├── .claude/ │ ├── rules/ │ ├── skills/ │ ├── agents/ │ └── settings.json │ └── .cursor/ ├── rules/ ├── skills/ ├── agents/ ├── hooks.json └── mcp.json ``` There is an even better approach for many teams: ```text AGENTS.md │ ├──────────────► Cursor │ └──────────────► CLAUDE.md │ └── Claude Code ``` Claude Code currently does **not** automatically treat `AGENTS.md` as its primary instruction file, but it supports importing it from `CLAUDE.md`. Its documentation explicitly recommends this pattern when a repository already uses `AGENTS.md`. ([Claude](https://code.claude.com/docs/en/memory)) For example: ```markdown # CLAUDE.md @AGENTS.md ## Claude Code-specific instructions Use plan mode for architectural changes. Before modifying database migrations: 1. Inspect existing migrations. 2. Check the current schema. 3. Confirm backward compatibility. ``` That allows both tools to share the core engineering instructions. * * * # 4\. Step One — Create the Project Let's use a typical stack: ```text Backend: Node.js TypeScript NestJS PostgreSQL Redis Frontend: React TypeScript Testing: Jest Playwright Tooling: ESLint Prettier GitHub Actions ``` Create the project: ```bash mkdir my-project cd my-project git init ``` A basic structure: ```text my-project/ ├── apps/ │ ├── api/ │ └── web/ │ ├── packages/ │ ├── shared/ │ └── config/ │ ├── docs/ │ ├── architecture/ │ ├── api/ │ └── decisions/ │ ├── tests/ │ ├── package.json └── README.md ``` For a monorepo, the AI instructions become even more important because different applications can have different conventions. * * * # 5\. Step Two — Create `AGENTS.md` This is your **high-level engineering contract**. Keep it concise. Cursor recommends splitting large rule sets into focused files, and Claude Code recommends keeping `CLAUDE.md` concise because these instructions consume context. ([Cursor](https://prod.cursor.com/help/customization/rules?utm_source=chatgpt.com)) Example: ```markdown # Project Instructions ## Project This is a production TypeScript monorepo. ## Structure - `apps/api` - NestJS backend - `apps/web` - React frontend - `packages/shared` - Shared TypeScript types - `packages/config` - Shared configuration - `docs` - Architecture and engineering documentation ## General Rules - Use TypeScript. - Do not introduce `any` unless explicitly justified. - Reuse existing utilities before creating new ones. - Do not duplicate business logic. - Follow existing architectural patterns. - Do not modify generated files manually. - Do not modify unrelated files. ## Testing Every behavioral change must include appropriate tests. Before completing a task: 1. Run unit tests. 2. Run type checking. 3. Run linting. 4. Review the final diff. ## Security Never: - Hardcode credentials. - Commit secrets. - Log passwords or tokens. - Disable authentication to make tests pass. - Disable security controls without explicit approval. - Trust user input without validation. ## Git Do not: - Force push. - Reset unrelated changes. - Delete user changes. - Modify unrelated files. ## Completion A task is complete only when: - Implementation is complete. - Tests pass. - Type checking passes. - Linting passes. - Security implications are considered. - Final changes are reviewed. ``` * * * # 6\. Step Three — Configure Claude Code Claude Code's project-level instruction file can be: ```text CLAUDE.md ``` or: ```text .claude/CLAUDE.md ``` Claude's current documentation also supports: ```text CLAUDE.local.md ``` for personal project-specific instructions, which should normally be gitignored. ([Claude](https://code.claude.com/docs/en/memory)) I recommend: ```text my-project/ │ ├── AGENTS.md ├── CLAUDE.md │ └── .claude/ ├── rules/ ├── skills/ ├── agents/ └── settings.json ``` And: ```markdown # CLAUDE.md @AGENTS.md ## Claude Code Workflow For substantial changes: 1. Explore the relevant code. 2. Identify applicable rules. 3. Create an implementation plan. 4. Implement incrementally. 5. Run tests. 6. Review the diff. 7. Report remaining risks. Do not make broad architectural changes unless explicitly requested. ``` Claude Code's `/init` can generate or improve a starting `CLAUDE.md` by analyzing the repository. Current versions can also help establish skills and hooks through the newer initialization flow. ([Claude](https://code.claude.com/docs/en/memory)) * * * # 7\. Claude Code Rules Now create: ```text .claude/rules/ ├── architecture.md ├── coding-style.md ├── security.md ├── testing.md ├── backend.md └── frontend.md ``` Claude Code supports modular `.claude/rules/` files, including path-specific rules. ([Claude](https://code.claude.com/docs/en/memory)) For example: ```markdown --- paths: - "apps/api/**/*.ts" --- # Backend Rules ## Controllers Controllers should: - Validate input. - Delegate business logic to services. - Avoid database queries directly. ## Services Services contain business logic. ## Database Use the repository/data-access layer. Do not access PostgreSQL directly from controllers. ``` This is much better than putting every rule into one giant file. * * * # 8\. Cursor Rules Cursor's equivalent is: ```text .cursor/rules/ ``` with `.mdc` files. For example: ```text .cursor/rules/ ├── project.mdc ├── backend.mdc ├── frontend.mdc ├── security.mdc └── testing.mdc ``` A Cursor rule: ```markdown --- description: Backend architecture rules for NestJS services globs: - "apps/api/**/*.ts" alwaysApply: false --- # Backend Architecture Controllers should only handle: - HTTP concerns - Request validation - Response mapping Business logic belongs in services. Database access belongs in repositories. Do not place business logic in controllers. ``` Cursor supports project rules with different application modes: always, intelligently, file-specific, or manually. ([Cursor](https://prod.cursor.com/docs/rules?utm_source=chatgpt.com)) ### Important Do not use the old: ```text .cursorrules ``` for new projects. Cursor documents `.cursorrules` as legacy and recommends migrating to `.cursor/rules/*.mdc` or `AGENTS.md`. ([Cursor](https://prod.cursor.com/help/customization/rules?utm_source=chatgpt.com)) * * * # 9\. Rules vs Instructions This distinction is extremely important. Don't put everything into `AGENTS.md`. Think about the hierarchy like this: ```text AGENTS.md ↓ "What is this project and what are the global rules?" Rules ↓ "How should this particular type of code be implemented?" Skills ↓ "How should I perform this reusable workflow?" Subagents ↓ "Who should specialize in this task?" Hooks ↓ "What must be validated or blocked automatically?" ``` For example: ### AGENTS.md ```text Use TypeScript. Run tests before completion. Never commit secrets. ``` ### Security rule ```text Validate authentication and authorization. Never trust request input. ``` ### Security skill ```text Perform a complete security audit. Run scanners. Trace input flows. Generate findings. ``` ### Security subagent ```text Act as a senior application security engineer. ``` ### Hook ```text Block execution if a secret is detected. ``` Each mechanism has a different purpose. * * * # 10\. Skills: Build Reusable AI Workflows This is where AI project scaffolding becomes genuinely powerful. Instead of repeatedly telling the agent: > "Review this code for security vulnerabilities." create a reusable: ```text security-audit ``` skill. Claude Code supports skills that package reusable workflows, instructions and resources. Cursor also implements Agent Skills as portable, version-controlled packages. ([Claude](https://code.claude.com/docs/en/skills)) Create: ```text .claude/skills/security-audit/SKILL.md ``` and: ```text .cursor/skills/security-audit/SKILL.md ``` The same `SKILL.md` can often be designed to work across both systems. Example: ```markdown --- name: security-audit description: Perform a production security audit of application code. --- # Security Audit ## Objective Identify confirmed security vulnerabilities in the requested code. ## Check - Hardcoded secrets - Authentication - Authorization - SQL injection - NoSQL injection - XSS - CSRF - SSRF - Command injection - Path traversal - Unsafe deserialization - File upload vulnerabilities - Sensitive logging - CORS - Rate limiting - Dependency vulnerabilities ## Process 1. Inspect the changed files. 2. Understand the data flow. 3. Identify trust boundaries. 4. Trace user-controlled input. 5. Review authentication. 6. Review authorization. 7. Check sensitive data handling. 8. Run available security scanners. 9. Report confirmed findings. 10. Fix confirmed vulnerabilities. 11. Re-run validation. ## Finding Format For every issue provide: Severity: File: Location: Issue: Attack scenario: Recommended fix: ``` Cursor's current Skills implementation supports `SKILL.md`, optional scripts, references and assets, and automatically discovers skills from project skill directories. ([Cursor](https://prod.cursor.com/docs/skills?utm_source=chatgpt.com)) * * * # 11\. Build a Security Skill For a production Node.js application, I'd make this one of the first skills. ```text security-audit/ ├── SKILL.md ├── scripts/ │ ├── scan-secrets.sh │ ├── dependency-audit.sh │ └── security-check.sh └── references/ └── security-checklist.md ``` Then: ```markdown # Security Audit Before reporting completion: ## Static checks Run: gitleaks detect npm audit eslint ## Application checks Inspect: Authentication Authorization Input validation Database queries File uploads External requests Logging CORS Cookies JWT handling ``` This is better than relying purely on the model's reasoning. * * * # 12\. Add Local Security Scanning For example: ```bash gitleaks detect --source . ``` You can also run: ```bash npm audit ``` and your normal: ```bash npm run lint npm test npm run typecheck ``` Now the architecture becomes: ```text AI │ ▼ Security Skill │ ├── Code analysis ├── Gitleaks ├── Dependency audit └── Application checks │ ▼ Security findings │ ▼ Fix │ ▼ Re-run scanners ``` This is much safer than: ```text AI says "I checked security" ``` * * * # 13\. Subagents Some tasks deserve isolated expertise. Examples: ```text security-auditor code-reviewer debugger test-engineer architecture-reviewer ``` Claude Code supports custom subagents, and Cursor supports specialized subagents that can operate with isolated context. ([Claude](https://code.claude.com/docs/en/sub-agents)) Example: ```text security-auditor.md ``` ```markdown --- name: security-auditor description: Review application code for security vulnerabilities. --- You are a senior application security engineer. Analyze the requested changes. Prioritize: 1. Authentication 2. Authorization 3. Injection 4. Secrets 5. Sensitive data exposure 6. SSRF 7. XSS 8. CSRF 9. File upload security 10. Dependency vulnerabilities Do not report theoretical issues without evidence. For each finding provide: - Severity - File - Location - Evidence - Exploit scenario - Fix ``` * * * # 14\. Code Review Agent Create: ```text code-reviewer.md ``` Example: ```markdown --- name: code-reviewer description: Perform production-grade code review. --- Review the current changes. Check: ## Correctness - Logic errors - Edge cases - Race conditions ## Architecture - Layer violations - Coupling - Duplication ## Performance - N+1 queries - Excessive database calls - Unnecessary network calls - Memory problems ## Security - Input validation - Authorization - Sensitive information ## Testing - Missing tests - Weak assertions - Regression risks Only report actionable findings. ``` * * * # 15\. Hooks: The Enforcement Layer This is one of the most important concepts. Instructions are not enforcement. Claude's documentation explicitly distinguishes instructions from enforcement: `CLAUDE.md` guides model behavior, while hooks can be used when you need to block an action regardless of what the model decides. ([Claude](https://code.claude.com/docs/en/memory)) Therefore: ```text Rule: "Never commit secrets." ``` is useful. But: ```text Hook: "BLOCK the operation when a secret is detected." ``` is stronger. The ideal architecture is: ```text AI Agent │ ▼ Tool execution │ ▼ ┌───────────┐ │ Hook │ └─────┬─────┘ │ ┌──────┴──────┐ │ │ PASS BLOCK │ │ ▼ ▼ Execute tool Stop action ``` * * * # 16\. Example: Secret Detection Hook Create: ```text hooks/security/scan-secrets.sh ``` Example: ```bash #!/usr/bin/env bash set -euo pipefail if command -v gitleaks >/dev/null 2>&1; then gitleaks detect \ --source . \ --no-banner \ --exit-code 1 else echo "WARNING: gitleaks is not installed" fi ``` Then integrate it into your agent's lifecycle according to the tool's hook configuration. The exact hook configuration differs between Claude Code and Cursor, so keep the **scanner script shared** and the hook configuration tool-specific. * * * # 17\. Claude Code Hooks Claude Code has a comprehensive hook system with lifecycle events around tool execution and other agent operations. ([Claude](https://code.claude.com/docs/en/hooks)) A practical Claude setup might enforce: ```text Before shell execution ↓ Validate command ↓ Allow / Block After file modification ↓ Run formatting / validation Before sensitive operation ↓ Security checks ``` This is especially useful for: ```text rm -rf git reset git push --force production deployment database migrations secret exposure ``` * * * # 18\. Cursor Hooks Cursor also provides lifecycle hooks through its current customization architecture. Cursor describes hooks as scripts that observe, control or extend the agent loop. ([Cursor](https://prod.cursor.com/docs/customize-cursor?utm_source=chatgpt.com)) For example, conceptually: ```text beforeShellExecution ↓ validate-command.sh ``` and: ```text afterFileEdit ↓ format.sh ``` and: ```text beforeMCPExecution ↓ security validation ``` This lets you build a similar enforcement model in Cursor. * * * # 19\. MCP: Give the AI Real Tools MCP stands for **Model Context Protocol**. Instead of the AI only seeing your source code, MCP can expose external systems. For example: ```text AI Agent │ ┌──────────────┼───────────────┐ ▼ ▼ ▼ GitHub Jira DB │ │ │ ▼ ▼ ▼ PRs Tickets Schema ``` Claude Code and Cursor both support MCP integrations. ([Claude](https://code.claude.com/docs/en/mcp)) Useful MCP integrations include: ```text GitHub Jira Slack PostgreSQL Sentry Linear AWS Internal APIs Documentation ``` But don't expose everything. Follow least privilege. For example: ```text GitHub: ✓ Read repository ✓ Read issues ✓ Create PR ✗ Delete repository ✗ Modify organization settings ``` * * * # 20\. Practical MCP Example Suppose your team uses Jira. Without MCP: ```text Developer: "Implement JIRA-123." AI: "I need the ticket details." ``` You manually copy them. With MCP: ```text Developer: "Implement JIRA-123." AI ↓ Jira MCP ↓ Retrieve ticket ↓ Understand acceptance criteria ↓ Inspect code ↓ Implement ↓ Run tests ↓ Create PR ``` That is where AI starts becoming an actual development agent rather than a chatbot. * * * # 21\. Create Reusable Commands For repetitive workflows, create commands. Examples: ```text /review /security-audit /fix-issue /test /refactor /deploy ``` A `/review` workflow could be: ```markdown # Code Review 1. Inspect git diff. 2. Identify modified files. 3. Read relevant architecture rules. 4. Check correctness. 5. Check security. 6. Check performance. 7. Check tests. 8. Run tests. 9. Report findings by severity. ``` Cursor currently supports commands as reusable prompts, while its newer Skills system can also turn workflows into invocable `/skill-name` workflows. ([Cursor](https://prod.cursor.com/docs/customize-cursor?utm_source=chatgpt.com)) * * * # 22\. A Better Modern Approach: Commands vs Skills Don't blindly create both. Use: ### Skill When the AI should be able to decide: > "This task requires security auditing." Use: ```text security-audit/SKILL.md ``` ### Command When the developer explicitly says: > `/security-audit` Use an explicitly invoked workflow. ### Subagent When the task requires: > "Have a specialist independently analyze this." Use: ```text security-auditor ``` ### Hook When you need: > "This must be checked regardless of what the AI thinks." Use a hook. This distinction makes the system much cleaner. * * * # 23\. Recommended AI Workflow for a Feature Suppose you ask: > "Add a password reset API." A well-configured AI environment should behave approximately like this: ```text USER REQUEST │ ▼ Understand requirements │ ▼ Read AGENTS.md / CLAUDE.md │ ▼ Load backend/API rules │ ▼ Inspect authentication architecture │ ▼ Create implementation plan │ ▼ Implement │ ├── Controller ├── Service ├── Repository ├── DTO └── Tests │ ▼ Security Skill │ ├── Token security ├── Rate limiting ├── Enumeration risk ├── Input validation └── Sensitive logging │ ▼ Run tests │ ▼ Typecheck │ ▼ Lint │ ▼ Code Reviewer │ ▼ Final diff ``` This is significantly more reliable than simply: ```text "Claude, implement password reset." ``` * * * # 24\. Practical Debugging Workflow Suppose production has: ```text POST /api/orders 500 Internal Server Error ``` You can structure debugging like this: ```text Developer │ ▼ /debug │ ▼ Debugger Agent │ ├── Read logs ├── Trace request ├── Inspect service ├── Inspect database └── Reproduce issue │ ▼ Root Cause │ ▼ Minimal Fix │ ▼ Regression Test │ ▼ Code Review ``` The critical part is: > **Don't allow the AI to stop at "I found the likely cause."** Require: ```text Root cause + Fix + Regression test + Validation ``` * * * # 25\. Practical Database Migration Workflow Database changes deserve their own rules. Create: ```text database.mdc ``` Example: ```markdown --- description: Database migration rules globs: - "**/migrations/**" - "**/*.sql" --- # Database Rules Never modify an already-applied migration. For schema changes: 1. Create a new migration. 2. Make migrations backward compatible where possible. 3. Consider existing production data. 4. Consider indexes and query performance. 5. Test rollback strategy where supported. 6. Verify generated SQL. 7. Never drop production data without explicit approval. ``` Then create a migration skill: ```text database-migration/ └── SKILL.md ``` Now the AI has: ```text General instructions + Database-specific rules + Database migration workflow ``` without loading database-specific material into every task. * * * # 26\. Context Management Matters One of the biggest mistakes in AI coding projects is creating a gigantic: ```text CLAUDE.md ``` or: ```text AGENTS.md ``` containing 1,500 lines. That is counterproductive. Claude Code recommends keeping `CLAUDE.md` concise and moving multi-step or specialized procedures into skills or path-scoped rules. ([Claude](https://code.claude.com/docs/en/memory)) Cursor similarly recommends focused rules rather than one giant rule file. ([Cursor](https://prod.cursor.com/help/customization/rules?utm_source=chatgpt.com)) A good architecture is: ```text AGENTS.md │ ├── Always relevant │ └── ~100–200 lines Rules │ ├── Backend ├── Frontend ├── Security ├── Testing └── Database Skills │ ├── Deployment ├── Security audit ├── Debugging └── Migration ``` This gives the AI **progressive context** instead of dumping the entire engineering handbook into every request. * * * # 27\. Use Path-Specific Rules Suppose you have: ```text apps/api/ apps/web/ ``` Don't tell the AI about React conventions while it is editing NestJS code. Instead: ```text apps/api/**/*.ts ``` gets: ```text backend rules ``` while: ```text apps/web/**/*.tsx ``` gets: ```text frontend rules ``` Claude Code supports `paths` for conditional rules, while Cursor supports file-pattern-based rules through its `.mdc` configuration. ([Claude](https://code.claude.com/docs/en/memory)) This improves both relevance and context efficiency. * * * # 28\. The Security Architecture I Recommend For production development, I would implement this: ```text Developer │ ▼ AI Agent │ ┌────────┴────────┐ │ │ ▼ ▼ Rules Skills │ │ └────────┬────────┘ ▼ Implementation │ ▼ ┌──────────────┐ │ Hooks │ └──────┬───────┘ │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ Gitleaks Secretlint ESLint │ │ │ └──────────────┼──────────────┘ ▼ Tests │ ▼ Security Agent │ ▼ Code Reviewer │ ▼ Git Diff │ ▼ PR ``` The AI is therefore **inside the engineering controls**, not above them. * * * # 29\. Recommended Final Directory Structure For a production Node.js/NestJS/React project, I would use: ```text my-project/ │ ├── AGENTS.md ├── CLAUDE.md │ ├── apps/ │ ├── api/ │ └── web/ │ ├── packages/ │ ├── shared/ │ └── config/ │ ├── docs/ │ ├── architecture/ │ ├── api/ │ ├── decisions/ │ └── development/ │ ├── tests/ │ ├── .claude/ │ │ │ ├── rules/ │ │ ├── architecture.md │ │ ├── backend.md │ │ ├── frontend.md │ │ ├── security.md │ │ ├── testing.md │ │ └── database.md │ │ │ ├── skills/ │ │ ├── security-audit/ │ │ │ ├── SKILL.md │ │ │ ├── scripts/ │ │ │ └── references/ │ │ │ │ │ ├── code-review/ │ │ │ └── SKILL.md │ │ │ │ │ ├── debugging/ │ │ │ └── SKILL.md │ │ │ │ │ ├── testing/ │ │ │ └── SKILL.md │ │ │ │ │ └── deployment/ │ │ └── SKILL.md │ │ │ ├── agents/ │ │ ├── security-auditor.md │ │ ├── code-reviewer.md │ │ ├── debugger.md │ │ └── architecture-reviewer.md │ │ │ └── settings.json │ ├── .cursor/ │ │ │ ├── rules/ │ │ ├── project.mdc │ │ ├── architecture.mdc │ │ ├── backend.mdc │ │ ├── frontend.mdc │ │ ├── security.mdc │ │ ├── testing.mdc │ │ └── database.mdc │ │ │ ├── skills/ │ │ ├── security-audit/ │ │ │ └── SKILL.md │ │ ├── code-review/ │ │ │ └── SKILL.md │ │ ├── debugging/ │ │ │ └── SKILL.md │ │ └── deployment/ │ │ └── SKILL.md │ │ │ ├── agents/ │ │ ├── security-auditor.md │ │ ├── code-reviewer.md │ │ ├── debugger.md │ │ └── architecture-reviewer.md │ │ │ ├── hooks.json │ └── mcp.json │ ├── hooks/ │ ├── security/ │ │ ├── gitleaks.sh │ │ ├── secretlint.sh │ │ └── validate-command.sh │ │ │ ├── validation/ │ │ ├── lint.sh │ │ ├── format.sh │ │ └── typecheck.sh │ │ │ └── audit/ │ └── agent-audit.sh │ ├── .gitignore ├── package.json └── README.md ``` * * * # 30\. What Should Actually Be Shared Between Claude and Cursor? This is the part I would optimize carefully. You don't want: ```text Claude implementation + Cursor implementation + duplicated rules + duplicated skills ``` Instead: ```text Shared │ ┌───────┴────────┐ │ │ AGENTS.md Skills │ │ ┌──────┴──────┐ │ ▼ ▼ ▼ Claude Code Cursor Shared │ │ workflows │ │ .claude/ .cursor/ ``` Cursor's current Skills implementation explicitly supports compatibility with Claude skill directories, including `.claude/skills/`, which makes sharing skills considerably easier. ([Cursor](https://prod.cursor.com/docs/skills?utm_source=chatgpt.com)) Claude Code also supports importing other coding-agent configurations, including `AGENTS.md`, Cursor rules, MCP servers, commands, subagents and skills in current versions. ([Claude](https://code.claude.com/docs/en/memory)) That means the ecosystem is moving toward **portable AI development configuration**, rather than completely isolated tool-specific configurations. * * * # 31\. What I Would NOT Put in AI Instructions Avoid putting these into `CLAUDE.md` or `AGENTS.md`: ### Huge documentation ```text Full API documentation Full database schema Entire architecture document ``` Instead: ```text docs/ ``` and tell the AI where to find it. ### Temporary information Don't put: ```text Currently fixing ticket #123 ``` into permanent project instructions. ### Secrets Never: ```text API_KEY=xxxxx DATABASE_PASSWORD=xxxxx ``` AI configuration should reference environment variables. ### Extremely detailed procedures Move them into: ```text skills/ ``` ### Enforcement rules Don't rely on: ```text "Never run dangerous commands." ``` alone. Use hooks and permissions where available. * * * # 32\. The Golden Rule Think about your AI configuration as an engineering system: ```text KNOWLEDGE │ AGENTS.md │ ▼ RULES │ ▼ SKILLS │ ▼ SUBAGENTS │ ▼ TOOLS │ ▼ HOOKS │ ▼ VALIDATION ``` Each layer solves a different problem. ### `AGENTS.md` / `CLAUDE.md` **What should the AI know?** ### Rules **What standards must it follow?** ### Skills **How should it perform this type of task?** ### Subagents **Which specialist should handle this task?** ### MCP **Which external systems can it access?** ### Hooks **Which actions must be validated or blocked?** ### Tests **Did the implementation actually work?** * * * # 33\. My Recommended Starting Point Don't build the entire structure on day one. Start with this: ```text project/ │ ├── AGENTS.md ├── CLAUDE.md │ ├── .claude/ │ ├── rules/ │ │ ├── security.md │ │ ├── backend.md │ │ └── testing.md │ │ │ ├── skills/ │ │ ├── security-audit/ │ │ │ └── SKILL.md │ │ └── code-review/ │ │ └── SKILL.md │ │ │ └── agents/ │ ├── security-auditor.md │ └── code-reviewer.md │ └── .cursor/ ├── rules/ ├── skills/ ├── agents/ ├── hooks.json └── mcp.json ``` Then evolve it based on actual failures. If the AI repeatedly makes a mistake: ```text mistake #1 → fix manually mistake #2 → add a rule mistake #3 → automate it ``` That is the right way to grow the scaffolding. * * * # 34\. Final Architecture The end state should look less like: ```text Claude/Cursor ↓ Generate code ``` and more like: ```text ┌───────────────────┐ │ Developer │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ Claude / Cursor │ │ Agent │ └─────────┬─────────┘ │ ┌───────────┴───────────┐ │ │ ▼ ▼ Project Rules Skills │ │ └───────────┬───────────┘ │ ▼ Subagents │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ Developer Security Reviewer Agent Agent Agent │ │ │ └─────────────┼─────────────┘ ▼ MCP / Tools │ ▼ Code Changes │ ▼ Hooks │ ┌───────────┼───────────┐ ▼ ▼ ▼ Secrets Lint Tests │ │ │ └───────────┼───────────┘ ▼ Final Review │ ▼ PR ``` That is the fundamental shift from **AI-assisted coding** to an **AI-native software engineering workflow**. The current Claude Code and Cursor feature sets make this architecture practical: Claude Code provides persistent instructions, path-scoped rules, skills, subagents, hooks, MCP and auto memory; Cursor provides project rules/`AGENTS.md`, Agent Skills, subagents, hooks, MCP and a unified Customize/Plugin system. ([Claude](https://code.claude.com/docs/en/memory)) **The most important design principle is to keep the AI configuration modular and the enforcement deterministic.** Let the model reason about code, but let tests, scanners, permissions and hooks enforce the things that cannot safely depend on model compliance.