code-design
Code Design Principles — Agent Skill
You are setting up agent instructions for this project based on the 6 Principles of Good Code Design: Consistent, Correct, Clear, Concise, Simple, Salient.
Step 1: Check for Existing Files
Before writing anything, check if any of these files already exist in the project root:
CLAUDE.mdAGENTS.md.cursorrules.github/copilot-instructions.md
If any exist, show the user what was found and ask whether to:
- Merge the principles into the existing file
- Replace the existing file
- Cancel
Do not overwrite without explicit confirmation.
Step 2: Detect Project Stack
Scan the project root for configuration files to determine the stack:
| File | Stack |
|---|---|
package.json |
Node.js / TypeScript / JavaScript |
tsconfig.json |
TypeScript |
pyproject.toml |
Python (modern) |
setup.py / setup.cfg |
Python (legacy) |
Cargo.toml |
Rust |
go.mod |
Go |
Gemfile |
Ruby |
pom.xml / build.gradle |
Java / Kotlin |
mix.exs |
Elixir |
Package.swift |
Swift |
Also detect:
- Package manager: Look for
uv.lock,poetry.lock,pnpm-lock.yaml,yarn.lock,package-lock.json,Pipfile.lock - Test framework: Look for
pytest.ini,jest.config.*,vitest.config.*,.mocharc.*, test directories - Linter/formatter: Look for
.eslintrc.*,biome.json,ruff.toml,.prettierrc.*,rustfmt.toml
Step 3: Read the Template
Read the CLAUDE.md file located in this skill's directory (next to this SKILL.md file). This is the base template you will customize. For the full rationale behind each principle, see PRINCIPLES.md in the same directory.
Step 4: Generate the Instructions File
Using the template from Step 3, create a CLAUDE.md (or AGENTS.md if the user's agent platform prefers it) in the project root. The template includes Python and TypeScript as examples — adapt the language-specific sections to match the detected stack:
- Style Guide — Replace the Python/TypeScript subsections with idiomatic style entries for the detected language(s).
- Project Setup — Replace with actual setup instructions: package manager commands, build/test/lint scripts found in the project's config files (
package.jsonscripts,Makefile,pyproject.toml, etc.). The Python section in the template shows the level of detail expected.
Step 5: Confirm
After writing the file, tell the user:
- What file was created and where
- What stack was detected
- What sections were customized
- Suggest they review and adjust the Project Setup section for any project-specific tooling