|
1 | 1 | # GLOBAL CODING STANDARDS |
2 | 2 |
|
3 | | -## AGENT INSTRUCTIONS |
| 3 | +## Agent Instructions |
4 | 4 |
|
5 | | -**IMPORTANT**: As an agent, you MUST read and follow ALL guidelines in this document BEFORE executing any task in a task list. DO NOT skip or ignore any part of these standards. These standards supersede any conflicting instructions you may have received previously. |
| 5 | +Read and follow these standards before executing task-list work. They supersede conflicting lower-priority guidance. |
6 | 6 |
|
7 | | -## Pragmatic Software Engineering Assistant |
| 7 | +## Operating Principles |
8 | 8 |
|
9 | | -You are a pragmatic software engineer who prioritizes correctness and clarity over agreeability. Your job is to write quality code and challenge poor assumptions. |
10 | | - |
11 | | -## Core Behavior |
12 | | - |
13 | | -**Examine Before Coding:** |
14 | | - |
15 | | -- Study existing code patterns and conventions before making changes |
16 | | -- Identify the established architecture and follow it consistently |
17 | | -- Understand the project's design decisions and constraints |
18 | | - |
19 | | -**Be Direct:** |
20 | | - |
21 | | -- Give one focused solution as your primary recommendation |
22 | | -- Explain your reasoning concisely |
23 | | -- Point out problems with proposed approaches |
24 | | -- Don't sugarcoat feedback about code quality issues |
25 | | - |
26 | | -**Focus on Precision:** |
27 | | - |
28 | | -- Ask about edge cases, error handling, and performance requirements upfront |
29 | | -- Understand the actual problem before proposing solutions |
| 9 | +- Prioritize correctness and clarity over agreeability. |
| 10 | +- Examine the existing codebase before coding: study local patterns, architecture, and constraints, then follow them consistently. |
| 11 | +- Be direct: give one focused recommendation, explain the reasoning concisely, and call out quality issues. |
| 12 | +- Ask first when requirements, edge cases, error handling, or performance expectations are ambiguous. |
30 | 13 |
|
31 | 14 | ## Code Standards |
32 | 15 |
|
33 | | -- TypeScript strict mode assumed |
34 | | -- Node.js modules prefixed with `node:` |
35 | | -- Handle errors appropriately or explicitly state assumptions |
36 | | -- Follow language conventions strictly |
37 | | -- Use named imports for Node.js modules |
38 | | -- Always prefer promises like `node:fs/promises` instead of synchronous equivalents |
39 | | -- Consider security implications (input validation, sanitization) |
40 | | -- Prefer built-in solutions over external libraries unless there's clear justification |
41 | | - |
42 | | -## Comment Guidelines |
43 | | - |
44 | | -**Avoid redundant comments that restate obvious code** |
45 | | - |
46 | | -- Remove useless inline comments. Keep JSDoc comments. |
47 | | -- Remove obvious comments: Delete comments that merely restate what the code clearly does (e.g., '// increment counter' above 'counter++') |
48 | | - |
49 | | -### Comment Review Criteria |
50 | | - |
51 | | -When adding comments, always double-check and ask yourself: |
52 | | - |
53 | | -- Does this comment add value beyond what well-named code already communicates? |
54 | | -- Does it explain business logic, edge cases, or architectural decisions? → Keep |
55 | | -- Would this help a new developer understand non-obvious behavior? → Keep |
56 | | - |
57 | | -### Examples |
58 | | - |
59 | | -#### Remove (obvious) |
60 | | - |
61 | | -``` |
62 | | -// Increment the counter |
63 | | -counter += 1 |
| 16 | +- Assume TypeScript strict mode. |
| 17 | +- Prefix Node.js modules with `node:` and use named imports. |
| 18 | +- Prefer promise APIs such as `node:fs/promises` over synchronous equivalents. |
| 19 | +- Handle errors appropriately or explicitly state assumptions. |
| 20 | +- Follow language and project conventions. |
| 21 | +- Consider security implications, including input validation and sanitization. |
| 22 | +- Prefer built-in solutions over external libraries unless there is clear justification. |
64 | 23 |
|
65 | | -// Check if user is present |
66 | | -if (!user) { |
67 | | - return |
68 | | -} |
| 24 | +## Comments |
69 | 25 |
|
70 | | -// Loop through items |
71 | | -for (let item in items) { |
72 | | - process(item) |
73 | | -} |
74 | | -``` |
| 26 | +- Keep JSDoc documentation comments. |
| 27 | +- Remove inline comments that merely restate obvious code. |
| 28 | +- Add comments only when they explain non-obvious business logic, edge cases, browser behavior, or architectural decisions. |
75 | 29 |
|
76 | | -#### Keep (information that can't otherwise be inferred) |
| 30 | +Keep comments like this: |
77 | 31 |
|
78 | 32 | ```ts |
79 | 33 | /** |
80 | 34 | * Safari has historically had inconsistent behavior with programmatically |
81 | | - * focusing hidden or visually obscured form elements |
| 35 | + * focusing hidden or visually obscured form elements. |
82 | 36 | */ |
83 | 37 | if (isSafari()) { |
84 | 38 | element.focus() |
85 | 39 | } |
86 | 40 | ``` |
87 | 41 |
|
88 | | -Always keep JSDoc documentation comments: |
| 42 | +Remove comments like this: |
89 | 43 |
|
90 | 44 | ```ts |
91 | | -export interface ConfigLoaderOptions { |
92 | | - /** |
93 | | - * Path to the qui-docs config file. This is automatically detected if omitted. |
94 | | - */ |
95 | | - configFile?: string |
| 45 | +// Increment the counter |
| 46 | +counter += 1 |
| 47 | + |
| 48 | +// Check if user is present |
| 49 | +if (!user) { |
| 50 | + return |
96 | 51 | } |
97 | 52 | ``` |
98 | 53 |
|
99 | 54 | ## Repository Structure |
100 | 55 |
|
101 | | -For each framework (currently only react and angular), the code is organized into modules as follows: |
102 | | - |
103 | | -- `packages/frameworks/<framework>-core` |
104 | | - - core library that contains most of the logic for each component. |
105 | | -- `packages/frameworks/<framework>` |
106 | | - - these components extend the core implementation and provide the QDS design system abstraction from the `packages/utilities/qds-core` package. This includes things like CSS classes, QDS-specific properties, etc. |
107 | | -- `packages/docs/<framework>-docs` |
108 | | - - library usage documentation. Each component's documentation lives here. |
109 | | - - usage examples are located as individual demo components at `packages/docs/<framework>/src/routes/components+/<component>+/demos/*` |
110 | | - - the markdown documentation with explanations is located at `packages/docs/<framework>/src/routes/components+/<component>+/_<component>.mdx` |
111 | | - - Examples: |
112 | | - - the `button` component's documentation lives at `packages/docs/<framework>/src/routes/components+/button+/_button.mdx`. |
113 | | - - the `button` component's demos live at `packages/docs/<framework>/src/routes/components+/button+/demos/*.tsx`. |
| 56 | +Code is organized into shared core packages, framework core packages, QDS framework packages, and docs: |
114 | 57 |
|
115 | | -Guidelines: |
| 58 | +- `packages/common/core`: shared, framework-agnostic component logic. |
| 59 | +- `packages/common/dom`: DOM utilities and helpers. |
| 60 | +- `packages/common/utils`: shared general-purpose utilities. |
| 61 | +- `packages/common/qds-core`: QDS design tokens, styles, and design-system primitives. |
| 62 | +- `packages/frameworks/<framework>-core`: core library logic for each component. |
| 63 | +- `packages/frameworks/<framework>`: QDS-specific component wrappers and abstractions, including CSS classes and QDS properties from `packages/common/qds-core`. |
| 64 | +- `packages/docs/<framework>-docs`: library usage documentation for the framework. |
116 | 65 |
|
117 | | -- When translating examples from one framework to another, examine the component code to determine the appropriate interfaces. The interfaces are similar between frameworks, but not exactly the same. For example, Angular controlled state often uses Angular Forms. |
118 | | -- When attempting to run a script from a package: First check the repository root package.json for the package's alias. If it exists, run the script using `pnpm <alias> <script>`. |
| 66 | +For component behavior changes, inspect the lowest relevant layer first. Shared behavior may belong in `packages/common/core`; framework-specific behavior belongs in `packages/frameworks/<framework>-core`; QDS styling and public design-system affordances belong in `packages/frameworks/<framework>`. |
119 | 67 |
|
120 | | -### Design Tokens |
| 68 | +Component docs live under the framework docs package: |
121 | 69 |
|
122 | | -- Design tokens are located in the `packages/common/qds-core/src/styles` directory. The format is the same for each supported brand and theme. Use `qualcomm-dark.css` as a reference. |
123 | | -- The Tailwind Plugin is located in the `packages/common/tailwind-plugin` directory. |
| 70 | +- MDX: `packages/docs/<framework>-docs/src/routes/components+/<component>+/_<component>.mdx` |
| 71 | +- Demos: `packages/docs/<framework>-docs/src/routes/components+/<component>+/demos/*` |
124 | 72 |
|
125 | | -## Documentation Strategy |
| 73 | +Examples: |
126 | 74 |
|
127 | | -When writing documentation, follow these guidelines: |
| 75 | +- Button docs: `packages/docs/angular-docs/src/routes/components+/button+/_button.mdx` |
| 76 | +- Button demos: `packages/docs/angular-docs/src/routes/components+/button+/demos/*.ts` |
128 | 77 |
|
129 | | -- Do not speak like an AI. Avoid emojis, EM-dashes, and fake enthusiasm. |
130 | | -- Speak like a human |
131 | | -- Analyze the existing tone and speech style of the documentation, then replicate it |
132 | | -- Always use the docs subagent |
| 78 | +When translating examples between frameworks, inspect the component code first. Interfaces are similar but not identical; Angular controlled state often uses Angular Forms. |
133 | 79 |
|
134 | | -## Testing Strategy |
| 80 | +## Project Workflow |
135 | 81 |
|
136 | | -- Use the react-tester subagent to write React tests. |
137 | | -- Use the angular-tester subagent to write Angular tests. |
| 82 | +- Run package-level tasks through package scripts. Check the root `package.json` for an alias and use `pnpm <alias> <script>` when available. Otherwise use `pnpm -C <relative/path/to/package> <script>`. |
| 83 | + - Do not use generic tool invocations such as `pnpm exec vitest` unless no package script exists. |
| 84 | +- Design tokens live in `packages/common/qds-core/src/styles`; use `qualcomm-dark.css` as a reference. |
| 85 | +- The Tailwind plugin lives in `packages/common/tailwind-plugin`. |
| 86 | +- Match the project's formatting configuration and surrounding style. |
138 | 87 |
|
139 | | -## Code Formatting |
| 88 | +## Documentation |
140 | 89 |
|
141 | | -- Match the project's existing formatting configuration |
142 | | -- Maintain consistency with the surrounding code style |
| 90 | +- Do not speak like an AI. Avoid emojis, EM-dashes, and fake enthusiasm. |
| 91 | +- Match the existing documentation tone. |
| 92 | +- Always use the docs agent. |
143 | 93 |
|
144 | | -## Response Format |
| 94 | +## Testing |
145 | 95 |
|
146 | | -1. Ask questions first if anything is ambiguous |
147 | | -2. State assumptions clearly when making them |
148 | | -3. Provide one well-reasoned solution with brief explanation |
149 | | -4. Mention alternative approaches only when they involve significant tradeoffs |
150 | | -5. Identify potential issues with the approach |
| 96 | +- Use the testing skills to write tests. |
151 | 97 |
|
152 | | -## What NOT to do |
| 98 | +## Response Format |
153 | 99 |
|
154 | | -- Don't introduce new patterns without understanding why existing ones exist |
155 | | -- Don't agree just to be helpful if you think something breaks consistency |
156 | | -- Don't write code without examining how similar problems are solved elsewhere |
157 | | -- Don't ignore established abstractions in favor of "simpler" solutions |
158 | | -- Don't overengineer when the project favors simpler approaches |
| 100 | +1. Ask questions first if anything is ambiguous. |
| 101 | +2. State assumptions clearly. |
| 102 | +3. Provide one well-reasoned solution with brief explanation. |
| 103 | +4. Mention alternatives only when they involve significant tradeoffs. |
| 104 | +5. Identify potential issues with the approach. |
159 | 105 |
|
160 | | -**Always examine the existing codebase first.** Understand the patterns, respect the architecture, and maintain consistency while improving quality. |
| 106 | +## What Not To Do |
161 | 107 |
|
162 | | -Be skeptical. Be precise. Challenge me when I'm wrong. |
| 108 | +- Do not introduce new patterns without understanding why existing ones exist. |
| 109 | +- Do not agree just to be helpful if something breaks consistency. |
| 110 | +- Do not ignore established abstractions in favor of simpler-looking alternatives. |
| 111 | +- Do not overengineer when the project favors simpler approaches. |
0 commit comments